3 Using raco pkg

▼ |  | Package Management in Racket

1 | Getting Started with Packages
2 | Package Concepts
3 | Using raco pkg
4 | Package Metadata
5 | Source, Binary, and Built Packages
6 | Developing Packages with Git
7 | Package APIs
8 | Package Catalog Protocol
9 | PLane T Compatibility
10 | FAQ
11 | Future Plans
12 | How Package Installation and Distribution Works

► | 3 | Using raco pkg

3.1 | raco pkg install
3.2 | raco pkg update
3.3 | raco pkg uninstall
3.4 | raco pkg remove
3.5 | raco pkg new
3.6 | raco pkg show
3.7 | raco pkg migrate
3.8 | raco pkg create
3.9 | raco pkg config
3.10 | raco pkg catalog-show
3.11 | raco pkg catalog-copy
3.12 | raco pkg catalog-archive
3.13 | raco pkg archive
3.14 | raco pkg empty-trash

On this page:

3.1 raco pkg install
3.2 raco pkg update
3.3 raco pkg uninstall
3.4 raco pkg remove
3.5 raco pkg new
3.6 raco pkg show
3.7 raco pkg migrate
3.8 raco pkg create
3.9 raco pkg config
3.10 raco pkg catalog-show
3.11 raco pkg catalog-copy
3.12 raco pkg catalog-archive
3.13 raco pkg archive
3.14 raco pkg empty-trash

Racket
top contents ← prev up next →

## 3 Using raco pkg🔗ℹ

The raco pkg command provides package-management tools via sub-commands.

### 3.1 raco pkg install🔗ℹ

raco pkg install ‹option› ... ‹pkg-source› ... — Installs the given package sources (eliminating exact-duplicate ‹pkg-source›s). If a given ‹pkg-source› is auto-installed (to satisfy some other package’s dependency), then it is promoted to explicitly installed.

If no ‹pkg-source›s are supplied and the --clone flag is not supplied, the current directory is installed as a link. See the --link flag below for more details.

If no ‹pkg-source›s are supplied and the --clone flag is supplied, then the clone directory’s name is used as the only ‹pkg-source› argument. See the --clone flag below for more details.

The install sub-command accepts the following ‹option›s:

- --type ‹type› or -t ‹type› — Specifies an interpretation of the package source, where ‹type› is either file, dir, file-url, dir-url, git, git-url, github, or name. The difference between git and git-url is that a .git suffix is added to a http or https URL for type git, but not for type git-url. The type is normally inferred for each ‹pkg-source›.

- --name ‹pkg› or -n ‹pkg› — Specifies the name of the package, which makes sense only when a single ‹pkg-source› is provided. The name is normally inferred for each ‹pkg-source›.

- --checksum ‹checksum› — Specifies a checksum for the package, which normally makes sense only when a single ‹pkg-source› is provided. The use of ‹checksum› depends on ‹pkg-source›: for a Git or GitHub source, ‹checksum› selects a checksum; for a package name, file path, or remote URL as a source, ‹checksum› specifies an expected checksum; for a directory path (including a remote directory URL without a ".CHECKSUM" file) as a source, ‹checksum› assigns a checksum.

- --deps ‹behavior› — Selects the behavior for dependencies, where ‹behavior› is one of

  - fail — Cancels the installation if dependencies are uninstalled or version requirements are unmet. This behavior is the default for non-interactive mode.

  - force — Installs the package(s) despite missing dependencies or version requirements. Forcing an installation may leave package content in an inconsistent state. Implied packages via implies or update-implies (see Package Metadata) are not updated, even if --ignore-implies is not specified.

  - search-ask — Looks for dependencies (when uninstalled) or updates (when version requirements are unmet) via the configured package catalogs, but asks the user whether packages should be installed or updated. This behavior is the default in interactive mode.

  - search-auto — Like search-ask, but does not ask for permission to install or update a dependency.

  Unless --ignore-implies is specified, when a package is updated or installed, any package that it implies via implies or update-implies (see Package Metadata) is automatically updated independent of fail, search-ask, or search-auto, but implied dependencies are not updated for force behavior.

- --auto — Shorthand for --deps search-auto.

- --update-deps — With search-ask or search-auto dependency behavior, checks already-installed dependencies transitively for updates (even when not forced by version requirements, implies, or update-implies), asking or automatically updating a package when an update is available.

  Unless --ignore-implies or --deps force is specified, when a package is updated or installed, any package that it implies implies or update-implies (see Package Metadata) is automatically updated independent of the behavior requested via --update-deps.

- --ignore-implies — Disables special treatment of dependencies that are listed in implies or update-implies (see Package Metadata) for an installed or updated package.

- --link — Implies --type dir and links the existing directory as an installed package, instead of copying the directory’s content to install. Directory package sources are treated as links by default, unless --copy is specified or the directory name was reported by a catalog instead of specified directly.

  The package is identified as a single-collection package or a multi-collection package at the time that it is installed, and that categorization does not change even if the collection definition in "info.rkt" is changed (i.e., the package must be uninstalled and re-installed for the change to take effect).

- --static-link — Implies --link, and also indicates that subdirectories of the given directory will not change for each given directory that implements a multi-collection package.

- --copy — Disables default handling of directory package sources as links, and instead treats them like other sources: package content is copied to install.

- --clone ‹dir› — A Git or GitHub package source is cloned as ‹dir› and locally linked as the package implementation. See also Linking a Git Checkout as a Clone.

  If no ‹pkg-source› is supplied, then the last path element of ‹dir› is used as a package name and used as a ‹pkg-source› argument.

  Multiple ‹pkg-source› arguments make sense only if they all specify the same Git repository (with different paths into the repository). The --clone flag implies --type in the sense that each ‹pkg-source› must be either a Git or GitHub package source or a package name, where a package name must be mapped by the package catalog to a Git or GitHub package source.

- --source — Strips built elements of a package before installing, and implies --copy. See also Source, Binary, and Built Packages.

- --binary — Strips source elements of a package before installing, and implies --copy. See also Source, Binary, and Built Packages.

- --binary-lib — Strips source and documentation elements of a package before installing, and implies --copy. See also Source, Binary, and Built Packages.

- --scope ‹scope› — Selects the package scope for installation, where ‹scope› is one of

  - installation — Install packages for all users of a Racket installation, rather than user-specific.

  - user — Install packages for the current user and current installation’s name/version.

  The default package scope is normally user, but it can be configured with raco pkg config --set default-scope ‹scope›. The default installation name is normally the Racket version, but it can be configured with raco pkg config --set name ‹name›.

- -i or --installation — Shorthand for --scope installation.

- -u or --user — Shorthand for --scope user.

- --scope-dir ‹dir› — Select ‹dir› as the package scope.

- --catalog ‹catalog› — Uses ‹catalog›s instead of of the currently configured package catalogs. This flag can be provided multiple times. The catalogs are tried in the order provided.

- --skip-installed — Ignores any ‹pkg-source› whose name corresponds to an already-installed package, except for promoting auto-installed packages to explicitly installed.

- --pkgs — Disables default installation of the current directory when no ‹pkg-source›s are supplied.

- --all-platforms — Considers package dependencies independent of the current platform (instead of filtering dependencies to platforms other than the current one).

- --force — Ignores module conflicts, including conflicts due to installing a single package in multiple scopes. Forcing an installation may leave package content in an inconsistent state. Implies --force-strip.

- --force-strip — When using --source, --binary, or --binary-lib, ignore a mismatch between the package’s state and the requested state.

- --ignore-checksums — Ignores errors verifying package checksums (unsafe).

- --strict-doc-conflicts — Refuses to install in user package scope when documentation-directory names would conflict with other packages. “Conflicting” documentation names are normally allowed for installation in user package scope, but strict checking ensures that installation would succeed in other package scopes.

- --no-cache — Disables use of the download cache.

- --multi-clone ‹mode› — Specifies the handling of packages that are from the same Git repository but are installed with different clone-linking modes or different clone directories. (See also Developing Packages with Git.) The following modes are available:

  - convert — Converts non-clone-linked packages (either newly or previously installed) to clone-linked packages, assuming that the packages that are clone-linked all use the same clone directory. If clone-linked packages currently use different clone directories, installation fails.

  - ask — In the case when packages can be converted, ask the user whether to convert or allow the different clone-linking modes or clone directories. If converting is not an option, the installation fails. This clone-handling mode is the default in interactive mode.

  - fail — Reports an error and cancels the installation (the default in non-interactive mode).

  - force — Allows packages to have different clone-linking modes or clone directories.

- --pull ‹mode› — Specifies the way that commits are merged to clone-linked packages (see Developing Packages with Git) on installation or update. The following modes are available:

  - ff-only — Commits are merged using --ff-only, and installation fails if the fast-forward merge fails.

  - try — Like ff-only, but if the fast-forward fails, the repository checkout is left as-is, and installation continues.

  - rebase — Commits are merged using git rebase instead of git merge.

- --dry-run — Prevents changes to the current installation. All installation and update work is staged and checked, but the final installation step is skipped.

- --no-setup — Does not run raco setup after installation. This behavior is also the case if the environment variable PLT_PKG_NOSETUP is set to any non-empty value.

- --no-docs or -D — Does not render documentation during setup after installation. This flag has no effect with --no-setup.

- --recompile-only —Constrains raco setup to at most recompile a module from machine-independent form, reporting an error if compilation from source is needed. This behavior is useful as a sanity check when installing built packages (to ensure that they are properly built), but if a compilation error is reported, it will be after the package is installed.

- --recompile-cache ‹dir› — cache module recompilations (from machine-independent format to machine-dependent format) in ‹dir›.

- --jobs ‹n› or -j ‹n› — Installs and runs raco setup with ‹n› parallel jobs.

- --batch — Disables interactive mode, suppressing potential prompts for a user (e.g., about package dependencies or clone sharing).

- --no-trash — Refrains from moving updated or uninstalled packages to a trash folder.

- --fail-fast — Breaks raco setup as soon as any error is encountered.

Changed in version 6.1.1.5: Added the --batch, --clone, and --multi-clone flags.
Changed in version 6.1.1.6: Added the --no-trash flag, and changed the --deps default to depend only on interactive mode.
Changed in version 6.1.1.8: Added the --pull flag.
Changed in version 6.4.0.14: Added the --dry-run flag.
Changed in version 7.2.0.8: Added the --recompile-only flag.
Changed in version 7.4.0.4: Added the --no-docs, -D flags.
Changed in version 7.6.0.14: Allowed multiple --catalog flags.
Changed in version 8.0.0.13: Added git-url as a --type option.
Changed in version 8.17.0.2: Added the --recompile-cache flag.
Changed in version 8.18.0.7: Added the --force-strip flag.

### 3.2 raco pkg update🔗ℹ

raco pkg update ‹option› ... ‹pkg-source› ... — Checks the specified package names for package updates or replaces existing package installations with the given sources. If an update or replacement cannot be installed (e.g. it conflicts with another installed package), then this command fails without installing any of the ‹pkg-source›s (or their dependencies).

The treatment of a ‹pkg-source› depends on the way that it parses:

- When a ‹pkg-source› parses as a package name, then the named package must be installed already, and it is checked for updates. The --lookup and --clone flags change this interpretation of ‹pkg-source›.

- If ‹pkg-source› parses as a directory package source, and if the named package is installed as a link to a Git repository clone, then the clone is checked for updates. The --link, --static-link, and --copy flags change this interpretation of ‹pkg-source›.

- Otherwise, ‹pkg-source› specifies a package source to replace the current installation of the named package.

If no ‹pkg-source›, --all or -a flag, or --clone flag is specified, and if the current directory is within a package, then the enclosing package is updated. If no ‹pkg-source› is specified, but --clone is supplied, then the clone directory’s name is used as the only ‹pkg-source› argument.

If a package scope is not specified, the scope is inferred from the given ‹pkg-source›s.

The update sub-command accepts the following ‹option›s:

- --all or -a — Updates all packages, if no packages are given in the argument list.

- --lookup — Causes a package name as a ‹pkg-source› to be used as a replacement that is looked up in a catalog, instead of the name of an installed package that may have updates from its current source. (If the named package was installed through a package name, then there’s effectively no difference, unless a different catalog is used.)

  By default, if ‹pkg-source› refers to a package that is currently linked as a Git repository clone, then replacing the installation with a catalog-specified source has the effect of removing the clone link. However, the --lookup flag can be combined with the --clone flag (assuming that the catalog maps the package to a Git repository) so that the resulting installation is a linked repository clone.

- --type ‹type› or -t ‹type› — Same as for raco pkg install.

- --name ‹pkg› or -n ‹pkg› — Same as for raco pkg install.

- --checksum ‹checksum› — Same as for raco pkg install.

- --deps ‹behavior› — Same as for raco pkg install.

- --auto — Shorthand for --deps search-auto plus --update-deps.

- --update-deps — Same as for raco pkg install, but implied by --auto only for raco pkg update.

- --ignore-implies — Same as for raco pkg install.

- --link — Same as for raco pkg install, but a directory package source is treated as a link by default only when it does not correspond to a link or a Git repository clone.

- --static-link — Same as for raco pkg install.

- --copy — Same as for raco pkg install.

- --clone ‹dir› — Same as for raco pkg install, except that a ‹pkg-source› as a package name is treated as the name of an installed package (unless --lookup is specified). In that case, the package must be currently installed from a Git or GitHub source—possibly as directed by a catalog—and that source is used for the clone (which replaces the existing package installation).

  To convert a clone-linked package to a normal installation, use raco pkg update either with the --lookup flag or with a replacement package source that is not a package name.

- --unclone — An alias for --lookup, which (absent --clone) has the effect of replacing a link to a repository clone with a normal package installation.

- --binary — Same as for raco pkg install.

- --source — Same as for raco pkg install.

- --scope ‹scope› — Selects a package scope, the same as for raco pkg install.

- -i or --installation — Shorthand for --scope installation.

- -u or --user — Shorthand for --scope user.

- --scope-dir ‹dir› — Selects ‹dir› as the package scope, the same as for raco pkg install.

- --catalog ‹catalog› — Same as for raco pkg install.

- --skip-uninstalled — Ignores any ‹pkg-source› that does not correspond to an installed package.

- --all-platforms — Same as for raco pkg install.

- --force — Same as for raco pkg install.

- --force-strip — Same as for raco pkg install.

- --ignore-checksums — Same as for raco pkg install.

- --strict-doc-conflicts — Same as for raco pkg install.

- --no-cache — Same as for raco pkg install.

- --multi-clone ‹mode› — Same as for raco pkg install, except that when --lookup is specified and --clone is not specified, then conversion goes from clone to non-clone linking—but only for sharing differences implied by the immediate command-line arguments compared against existing package installations.

- --pull ‹mode› — Same as for raco pkg install

- --dry-run — Same as for raco pkg install.

- --no-setup — Same as for raco pkg install.

- --no-docs or -D — Same as for raco pkg install.

- --recompile-only — Same as for raco pkg install.

- --recompile-cache ‹dir› — Same as for raco pkg install.

- --jobs ‹n› or -j ‹n› — Same as for raco pkg install.

- --batch — Same as for raco pkg install.

- --no-trash — Same as for raco pkg install.

Changed in version 6.1.1.5: Added the --batch, --clone, and --multi-clone flags, and added update of enclosing package when no arguments are provided.
Changed in version 6.1.1.6: Added the --no-trash flag, and changed the --deps default to depend only on interactive mode.
Changed in version 6.1.1.8: Added the --skip-uninstalled and --pull flags.
Changed in version 6.4.0.14: Added the --dry-run flag.
Changed in version 6.90.0.27: Added the --unclone flag.
Changed in version 7.2.0.8: Added the --recompile-only flag.
Changed in version 7.4.0.4: Added the --no-docs, -D flags.
Changed in version 7.6.0.14: Allowed multiple --catalog flags.
Changed in version 8.17.0.2: Added the --recompile-cache flag.
Changed in version 8.18.0.7: Added the --force-strip flag.

### 3.3 raco pkg uninstall🔗ℹ

raco pkg uninstall ‹option› ... ‹pkg› ... — Attempts to uninstall the given packages. By default, if a package is the dependency of another package that is not listed, this command fails without removing any of the ‹pkg›s.

If a package scope is not specified, the scope is inferred from the given ‹pkg›s.

The uninstall sub-command accepts the following ‹option›s:

- --demote — “Uninstalls” explicitly installed packages by demoting them to auto-installed (leaving auto-installed packages as such). Combined with --auto, uninstalls packages for which there are no dependencies.

- --force — Ignores dependencies when removing packages.

- --auto — In addition to removing each ‹pkg›, uninstalls auto-installed packages (i.e., installed by the search-auto or search-ask dependency behavior, or demoted via --demote) that are no longer required by any explicitly installed package.

- --scope ‹scope› — Selects a package scope, the same as for raco pkg install.

- -i or --installation — Shorthand for --scope installation.

- -u or --user — Shorthand for --scope user.

- --scope-dir ‹dir› — Selects ‹dir› as the package scope, the same as for raco pkg install.

- --dry-run — Same as for raco pkg install.

- --no-setup — Same as for raco pkg install.

- --no-docs or -D — Same as for raco pkg install.

- --recompile-only — Same as for raco pkg install.

- --recompile-cache ‹dir› — Same as for raco pkg install.

- --jobs ‹n› or -j ‹n› — Same as for raco pkg install.

- --batch — Same as for raco pkg install.

- --no-trash — Same as for raco pkg install.

Changed in version 6.1.1.5: Added the --batch flag.
Changed in version 6.1.1.6: Added the --no-trash flag.
Changed in version 6.4.0.14: Added the --dry-run flag.
Changed in version 7.2.0.8: Added the --recompile-only flag.
Changed in version 7.4.0.4: Added the --no-docs, -D flags.
Changed in version 8.14.0.2: Renamed from raco pkg remove to raco pkg uninstall.
Changed in version 8.17.0.2: Added the recompile-cache flag.

### 3.4 raco pkg remove🔗ℹ

raco pkg remove — A synonym for raco pkg uninstall.

Changed in version 8.14.0.2: Made raco pkg remove an alias.

### 3.5 raco pkg new🔗ℹ

raco pkg new ‹pkg› — Populates a directory with the stubs for a new package, where ‹pkg› is the name of the new package. If ‹pkg› already exists as a directory in the current directory, no new package is created.

Added in version 6.1.1.5.

### 3.6 raco pkg show🔗ℹ

raco pkg show ‹option› ... ‹pkg› ... — Prints information about currently installed packages.

If ‹pkg›s are specified, then only those packages are shown. By default, packages are shown for all package scopes, but only for packages not marked as auto-installed. If a package is explicitly specified, it is shown even if it is marked as auto-installed. Unless -l or --long is specified, the output is roughly constrained to 80 columns or the number of columns specified by the COLUMNS environment variable. Unless --full-checksum is specified, checksums are abbreviated to 8 characters.

The show sub-command accepts the following ‹option›s:

- -a or --all — Includes auto-installed packages in the listing.

- -l or --long — Shows complete columns, instead of abbreviating to a width, and use a more regular (but less human-readable) format for some columns.

- --rx — Treats the ‹pkg›s as regular expressions for displaying specific packages.

- --full-checksum — Prints the full instead of the abbreviated checksum.

- -d or --dir — Adds a column in the output to show the directory where the package is installed.

- --scope ‹scope› — Shows only packages in ‹scope›, which is one of

  - installation — Show only installation-wide packages.

  - user — Show only user-specific packages for the current installation’s name/version or the name/version specified with --version or -v.

  The default is to show packages for all package scopes.

- -i or --installation — Shorthand for --scope installation.

- -u or --user — Shorthand for --scope user.

- --scope-dir ‹dir› — Shows only packages installed in ‹dir›.

- --version ‹vers› or -v ‹vers› — Show only user-specific packages for the installation name/version ‹vers›.

Changed in version 6.1.1.5: Added -l/--long and COLUMNS support.
Changed in version 6.1.1.6: Added explicit ‹pkg›s and --rx and --full-sha.

### 3.7 raco pkg migrate🔗ℹ

raco pkg migrate ‹option› ... ‹from-version› — Installs packages that were previously installed in user package scope for ‹from-version›, where ‹from-version› is an installation name/version.

The migrate sub-command accepts the following ‹option›s:

- --deps ‹behavior› — Same as for raco pkg install, except that search-auto is the default.

- --auto — Same as for raco pkg install; shorthand for --deps search-auto.

- --source — Same as for raco pkg install.

- --binary — Same as for raco pkg install.

- --binary-lib — Same as for raco pkg install.

- --scope ‹scope› — Same as for raco pkg install.

- -i or --installation — Shorthand for --scope installation.

- -u or --user — Shorthand for --scope user.

- --scope-dir ‹dir› — Select ‹dir› as the package scope.

- --catalog ‹catalog› — Same as for raco pkg install.

- --all-platforms — Same as for raco pkg install.

- --force — Same as for raco pkg install.

- --force-strip — Same as for raco pkg install.

- --ignore-checksums — Same as for raco pkg install.

- --strict-doc-conflicts — Same as for raco pkg install.

- --no-cache — Same as for raco pkg install.

- --dry-run — Same as for raco pkg install.

- --no-setup — Same as for raco pkg install.

- --no-docs or -D — Same as for raco pkg install.

- --recompile-only — Same as for raco pkg install.

- --recompile-cache ‹dir› — Same as for raco pkg install.

- --jobs ‹n› or -j ‹n› — Same as for raco pkg install.

Changed in version 6.4.0.14: Added the --dry-run flag.
Changed in version 7.2.0.8: Added the --recompile-only flag.
Changed in version 7.4.0.4: Added the --no-docs, -D flags.
Changed in version 7.6.0.14: Allowed multiple --catalog flags.
Changed in version 8.17.0.2: Added the --recompile-cache flag.
Changed in version 8.18.0.7: Added the --force-strip flag.

### 3.8 raco pkg create🔗ℹ

raco pkg create ‹option› ... ‹directory-or-package› — Bundles a package into an archive. Bundling is not needed for a package that is provided directly from a Git repository or other non-archive formats. The create sub-command can create an archive from a directory (the default) or from an installed package. It can also adjust the archive’s content to include only sources, only compiled bytecode and rendered documentation, or both—but packages are normally provided as source and converted to binary form by an automatic service, instead of by a package author.

The create sub-command accepts the following ‹option›s:

- --from-dir — Treats ‹directory-or-package› as a directory path; this is the default mode.

- --from-install — Treats ‹directory-or-package› as the name of an installed package (instead of a directory).

- --format ‹format› — Specifies the archive format. The allowed ‹format›s are: zip (the default), tgz, and plt. This option must be specified if --manifest is not present.

- --manifest — Creates a manifest file for a directory, rather than an archive.

- --as-is — Bundles all content of the package directory as is, with no filtering of sources, compiled files, or repository elements.

- --source — Bundles only sources in the package directory; see Source, Binary, and Built Packages.

- --binary — Bundles compiled bytecode and rendered documentation in the package directory; see Source, Binary, and Built Packages.

- --binary-lib — Bundles compiled bytecode only in the package directory; see Source, Binary, and Built Packages.

- --built — Bundles compiled sources, bytecode, and rendered documentation in the package directory, filtering repository elements; see Source, Binary, and Built Packages.

- --original ‹package› — Records ‹package› as the original source in the package’s "info.rkt" (but not in --as-is mode, since recording ‹package› means updating "info.rkt").

- --dest ‹dest-dir› — Writes generated bundles to ‹dest-dir›.

Changed in version 8.14.0.2: Added the --original flag.

### 3.9 raco pkg config🔗ℹ

raco pkg config ‹option› ... [‹key›] ‹val› ... — Views and modifies the configuration of the package manager. If ‹key› is not provided, the values for all recognized keys are shown. The ‹val› arguments are allowed only when --set is used, in which case the ‹val›s are used as the new values for ‹key›.

The config sub-command accepts with the following ‹option›s:

- --set — Sets an option, rather than printing it.

- --scope ‹scope› — Selects a package scope, the same as for raco pkg install. A configuration value set at installation scope serves as the default value at user scope.

- -i or --installation — Shorthand for --scope installation.

- -u or --user — Shorthand for --scope user.

- --scope-dir ‹dir› — Same as for raco pkg install.

The valid ‹key›s and corresponding ‹val›s are:

- name — A string for the installation’s name, which is used by user package scope and defaults to the Racket version.

- catalogs — A list of URLs for package catalogs. An empty-string ‹val› is replaced by the sequence of catalogs for the default configuration. A ‹val› that does not start with alphabetic characters followed by :// is treated as a path relative to the configuration directory (as reported by find-config-dir).

- default-scope — Either installation or user. The value of this key at user scope (possibly defaulting from installation scope) is the default package scope for raco pkg commands for which a scope is not inferred from a given set of package names (even for raco pkg config, which is consistent but potentially confusing).

- download-cache-dir — A directory that holds copies of downloaded packages, used to avoid re-downloading if the same URL and checksum combination is requested again. The default cache directory is user-specific (but not specific to a Racket version or installation name).

- download-cache-max-files — A limit on the number of files to be kept in the download cache directory.

- download-cache-max-bytes — A limit on the total size of files that are kept in the download cache directory.

- doc-open-url — A URL to use in place of a local filesystem path for viewing (or at least searching) documentation; an empty string, which is the default, disables the URL so that the local filesystem is used. This key can be set only in installation scope.

- git-checkout-credentials — A list that starts with a format specification (currently only 'basic is supported), followed by git credentials in the form ‹username›:‹password› that are tried when downloading packages with git sources using the HTTP or HTTPS protocols. The credentials are currently stored unencrypted on the filesystem.

- trash-max-packages — A limit on the number of package implementations that are kept in a trash folder when the package is uninstalled or updated.

- trash-max-seconds — A limit on the time since a package is uninstalled or updated that its implementation is kept in the trash folder. Package implementations are removed from a trash folder only when another package is potentially added to the trash folder or raco pkg empty-trash is used.

- network-retries — The number of times to retry a network communication that fails due to a connection error.

- network-timeout — The maximum number of seconds to wait for a network communication to complete, such as a download or a checksum fetch.

Changed in version 6.1.1.6: Added trash-max-packages and trash-max-seconds.
Changed in version 6.3: Added network-retries.
Changed in version 6.6.0.5: Added git-checkout-credentials.
Changed in version 9.0.0.2: Added network-timeout.

### 3.10 raco pkg catalog-show🔗ℹ

raco pkg catalog-show ‹option› ... ‹package-name› ... — Consults package catalogs for a package (that is not necessarily installed) and displays the catalog’s information for the package, such as its source URL and a checksum.

The catalog-show sub-command accepts the following ‹option›s:

- --all — Shows information for all available packages. When using this flag, supply no ‹package-name›s.

- --only-names — Shows only package names. This option is mainly useful with --all, but when a ‹package-name› is provided, catalogs are consulted to ensure that he package is available.

- --modules — Shows the modules that are implemented by a package.

- --catalog ‹catalog› — Queries ‹catalog›s instead of the currently configured package catalogs. This flag can be provided multiple times. The catalogs are tried in the order provided.

- --version ‹version› or -v ‹version› — Queries catalogs for a result specific to ‹version›, instead of the installation’s Racket version.

Changed in version 7.6.0.14: Allowed multiple --catalog flags.

### 3.11 raco pkg catalog-copy🔗ℹ

raco pkg catalog-copy ‹option› ... ‹src-catalog› ... ‹dest-catalog› — Copies information from the package catalog named by ‹src-catalog›s to a local database or directory ‹dest-catalog›, which can be used as a new package catalog.

The ‹src-catalog›s can be remote or local, while ‹dest-catalog› must be local (i.e., a directory path or a SQLite database path, as inferred from the path). If a ‹src-catalog› or ‹dest-catalog› does not start with a URL scheme, it is treated as a filesystem path. Information from multiple ‹src-catalog›s is merged, with information from earlier ‹src-catalog›s taking precedence over later ‹src-catalog›s.

The catalog-copy sub-command accepts the following ‹option›s:

- --from-config — Adds the currently configured package catalogs to the end of the ‹src-catalog›s list.

- --force — Replaces ‹dest-catalog› if it exists already.

- --merge — Adds to ‹dest-catalog› if it exists already. By default, information already in ‹dest-catalog› takes precedence over new information.

- --override — Changes merging so that new information takes precedence over information already in ‹dest-catalog›.

- --relative — Writes package sources to ‹dest-catalog› in relative-path form, when possible.

- --version ‹version› or -v ‹version› — Copies catalog results specific to ‹version› (for catalogs that make a distinction), instead of the installation’s Racket version.

### 3.12 raco pkg catalog-archive🔗ℹ

raco pkg catalog-archive ‹option› ... ‹dest-dir› ‹src-catalog› ... — Copies information from the package catalog named by ‹src-catalog›s to a "catalog" directory catalog in ‹dest-dir›, and also copies all package sources to a "pkgs" directory in ‹dest-dir›.

Packages sources are downloaded and repacked as needed, so that all packages are written to the "pkgs" directory as ".zip" archives. This conversion may change the checksum on each archived package.

The catalog-archive sub-command accepts the following ‹option›s:

- --from-config — Adds the currently configured package catalogs to the end of the ‹src-catalog›s list.

- --state ‹state-database› — To enable incremental updating, reads and writes the database ‹state-database›, which must have the suffix ".sqlite", as the current state of ‹dest-dir›.

- --relative — Writes package sources to ‹dest-catalog› in relative-path form.

- --version ‹version› or -v ‹version› — Copies catalog results specific to ‹version› (for catalogs that make a distinction), instead of the installation’s Racket version.

- --pkg-fail ‹mode› — Determines handling of failure for an individual package, such as when a ‹src-catalog› contains a bad package source. The following ‹mode›s are available:

  - fail (the default) — archiving stops and fails;

  - skip — the package is skipped and omitted from the archive catalog; or

  - continue — like skip, but raco pkg catalog-archive exits with a status code of 5 if any package was skipped.

- --include ‹pkg› — Can be specified multiple times. If --include is specified at least once, then the archive and generated catalog includes only the ‹pkg›s specified with --include, plus the dependencies of each ‹pkg› if --include-deps is specified, modulo packages excluded via --exclude.

- --include-deps — Modifies the --includes ‹pkg› flag to imply all dependencies of ‹pkg›.

- --include-deps-platform ‹sys› ‹subpath› — Modifies --include-deps to imply only dependencies that match the platform ‹sys›, which should be a possible result of (system-type), and ‹subpath›, which should be a possible result of (system-type 'platform)

- --exclude ‹pkg› — Can be specified multiple times. Removes ‹pkg› from the set of packages in the archive and generated catalog. If --include is used for the same ‹pkg›, then --exclude takes precedence. If --include is used with --include-deps for ‹pkg› or a package that depends on ‹pkg›, then --exclude stops the consideration of ‹pkg›’s dependencies (but does not necessarily exclude the dependencies, because they may be dependencies of an included package).

- --fast-file-copy — Directly copies package files from the ‹src-catalog›s when available on the local filesystem, instead of extracting and repacking.

Added in version 6.0.17.
Changed in version 7.7.0.1: Added --include, --include-deps, --include-deps-platform, --exclude, and --fast-file-copy.

### 3.13 raco pkg archive🔗ℹ

raco pkg archive ‹option› ... ‹dest-dir› ‹pkg› ... — Copies information from installed packages named by ‹pkgs›s to a "catalog" directory catalog in ‹dest-dir›, and also copies all package sources to a "pkgs" directory in ‹dest-dir›.

Packages sources are copied and repacked as needed, so that all packages are written to the "pkgs" directory as ".zip" archives. This conversion may change the checksum on each archived package.

The archive sub-command accepts the following ‹option›s:

- --include-deps — Includes the dependencies of the specified packages in the resulting catalog.

- --exclude ‹pkg› — Omits the specified ‹pkg› from the resulting catalog. This also causes the dependencies of ‹pkg› to be omitted if --include-deps is specified. This flag can be provided multiple times.

- --relative — Writes package sources to ‹dest-catalog› in relative-path form.

Added in version 6.1.0.8.

### 3.14 raco pkg empty-trash🔗ℹ

raco pkg empty-trash ‹option› ... — Removes or lists package implementations that were previously uninstalled or updated and are currently in the trash directory for the specified package scope. The trash-max-packages and trash-max-seconds configuration keys (see raco pkg config) control how many packages are kept in the trash directory and for how long.

The empty-trash sub-command accepts the following ‹option›s:

- --scope ‹scope› — Selects a package scope, the same as for raco pkg install.

- -i or --installation — Shorthand for --scope installation.

- -u or --user — Shorthand for --scope user.

- --scope-dir ‹dir› — Same as for raco pkg install.

- --list or -l — Shows the trash directory path and its content, instead of removing the current content.

Added in version 6.1.1.6.

top contents ← prev up next →