On this page:
2.1 Single-collection and Multi-collection Packages
2.2 Package Sources
2.3 Package Catalogs
2.4 Explicit vs. Auto-Installation
2.5 Package Conflicts
2.6 Package Updates
2.7 Package Scopes

2 Package Concepts🔗

A package is a set of modules in some number of collections. Modules installed using the Racket package manager are required like any other modules. For example, if the package tic-tac-toe contains the module "matrix.rkt" in a "data" collection, then after tic-tac-toe is installed,

(require data/matrix)

imports the module. The package name is not mentioned with require, because packages are a way of managing library collections, not a way of referencing them. It is common, however, for a package to implement a collection whose name is the same as the package name—in which case a require might appear to be referencing a package, but it is actually referencing a collection provided by the package.

Each package has associated package metadata:

A package is typically represented by a directory with the same name as the package. The checksum is typically left implicit. The package directory can contain a file named "info.rkt" to declare other metadata (see Package Metadata).

2.1 Single-collection and Multi-collection Packages🔗

A package can be a single-collection package or a multi-collection package:

2.2 Package Sources🔗

A package source identifies a package representation. Each package source type has a different way of storing the checksum and providing the package content (usually with single-collection package and multi-collection package variants).

The package source types are:

2.3 Package Catalogs🔗

A package catalog is a server or database that converts package names to other package sources. A package catalog is identified by a string representing a URL, where a http:// or https:// URL indicates a remote server, and a file:// URL indicates a local catalog in the form of an SQLite database or a directory tree.

PLT supports two package catalog servers that are enabled by default: https://pkgs.racket-lang.org for new packages and http://planet-compats.racket-lang.org for automatically generated packages for old PLaneT packages. Anyone may host a package catalog, and any file-serving HTTP host can act as a basic package catalog server. See Package Catalog Protocol for information on how package information is extracted from a catalog.

2.4 Explicit vs. Auto-Installation🔗

When a package is installed, the original source of its installation is recorded, as well as whether the installation was an automatic installation. An automatic installation is one that was installed because it was a dependency of some other package (as opposed to being installed explicitly by a user).

2.5 Package Conflicts🔗

Two packages are in conflict if they contain the same module. For example, if the package tic-tac-toe contains the module file "data/matrix.rkt" and the package factory-optimize contains the module file "data/matrix.rkt", then tic-tac-toe and factory-optimize are in conflict.

A package may also be in conflict with Racket itself, if it contains a module file that is part of the base Racket implementation. For example, any package that contains "racket/list.rkt" is in conflict with Racket.

For the purposes of conflicts, a module is a file that ends in ".rkt", ".ss", or ".scrbl", with the exception of files named "info.rkt".

2.6 Package Updates🔗

Package A is a package update of Package B if (1) B is installed, (2) A and B have the same name, and (3) A’s checksum is different than B’s. A single-collection package can be a package update of a multi-collection package and vice versa.

Note that a package version is not taken into account when determining a package update, although a change in a package’s version (in either direction) implies a change in the checksum because the checksum is computed from the package source and the meta-data that specifies the version is part of the source.

2.7 Package Scopes🔗

A package scope determines the effect of package installations, updates, etc., with respect to different users and Racket installations. The default package scope can be configured, but it is normally user, which makes actions specific to both the current user and the installation’s name/version (in the sense of get-installation-name). The installation scope means that package operations affect all users of the Racket installation.

A directory path can be used as a package scope, in which case package operations affect the set of packages installations in the directory. An installation can be configured to include the directory in its search path for installed packages (see Installation Configuration and Search Paths). When a directory path is used as a package scope, operations such as dependency checking will use all paths in the configured search path starting with the one that is designed as a package scope; if the designated path is not in the configured search path, then the directory by itself is used as the search path.

Conflict checking disallows installation of the same or conflicting package in different scopes, but if such a configuration is forced, collections are found first in packages with user package scope. Search then proceeds in a configured order, where installation package scope typically precedes other directory package scopes.

The default package scope is determined by first checking the configuration at 'user scope, and then checking for configuration in wider scopes like 'installation. If the default package scope is not configured in any scope, then it defaults to 'user.