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, github, or name. 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.

  • 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.

• --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), asking or automatically updating a package when an update is available. When a package is updated or installed, unless --skip-implies is specified, any package that it implies (see Package Metadata) is automatically updated independent of the behavior requested via --update-deps and --deps.

• --skip-implies — Disables special treatment of dependencies that are listed in 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 removed 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.

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

• --source — Strips built 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› instead of of the currently configured package catalogs.

• --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.

• --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.

• --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 removed 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.

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.

• --skip-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.

• --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.

• --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.

• --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.

3.3 raco pkg remove

raco pkg remove ‹option› ... ‹pkg› ... — Attempts to remove 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 remove sub-command accepts the following ‹option›s:

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

• --force — Ignores dependencies when removing packages.

• --auto — In addition to removing each ‹pkg›, removes 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.

• --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.

3.4 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.5 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.6 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.

Changed in version 6.4.0.14: Added the --dry-run flag.

3.7 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.

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

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

3.8 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.

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.

3.9 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 ‹packaee-name›s.

• --only-names — Shows only package names. This option is mainly useful with --all, but when a ‹packaee-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› instead of the currently configured package catalogs.

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

3.10 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.11 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.

Added in version 6.0.17.

3.12 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.13 raco pkg empty-trash

raco pkg empty-trash ‹option› ... — Removes or lists package implementations that were previously removed 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.