On this page:
1.1 What is a Package?
1.2 Inspecting Your Installation
1.3 Finding Packages
1.4 Installing Packages
1.5 Updating Packages
1.6 Removing Packages
1.7 Creating Packages
1.8 Sharing Packages
1.8.1 Git  Hub Deployment
1.8.2 Manual Deployment
1.8.3 Helping Others Discover Your Package
1.8.4 Naming and Designing Packages
1.8.5 Packages Compatible with Racket 5.3.5 and 5.3.6
5.92

1 Getting Started with Packages

There are two ways to manage Racket package installations:

We’ll use the raco pkg command to describe package-management operations here, but the graphical interface allows the same operations.

1.1 What is a Package?

A package is not something that you refer to directly in your Racket programs. Instead, a package is a set of libraries that fit into the collection hierarchy, and you refer to libraries through their collection-based paths. Libraries that are close in the hierarchy may be provided by different packages, while a single package may provide libraries that are far from each other in the hierarchy (but that are conceptually related, somehow).

Racket documentation tells you which package provides a given library. For example, the documentation for the pict/face library says that it is provided by the pict-lib package.If you’re reading this in a web browser, click pict/face to go straight to its documentation.

Over time, packages may be refactored so that a library moves to a different package, but the original package should continue to provide the library, too, by declaring a dependency on the new package. More generally, a package is intended to have an interface that only grows in terms of libraries, bindings, and functionality, which provides a basic level of backward compatibility. Incompatible changes should be implemented in a new package.

1.2 Inspecting Your Installation

To see the packages that you have installed already, use the raco pkg show subcommand:

  raco pkg show

Unless you have an especially minimal Racket installation, you will have packages installed already, probably listed in the “Installation-wide” section. In fact, if you have a typical Racket installation, then raco pkg show will initially show a main-distribution package and a racket-lib package:

  Installation-wide:

   Package              Checksum          Source

   main-distribution    01..........ef    (catalog main-distribution)

   racket-lib           fe..........01    (catalog racket-lib)

  User-specific for installation ....:

   [none]

The “Checksum” column reports the specific implementation of each package that is installed. A package can have a version in a more traditional sense, but the checksum is the “version” as far as the package system is concerned. When you request an update, then a package installation is updated if the current implementation of the package has a different checksum than the installed package, whether or not the package author adjusted the package’s version.

The “Source” column indicates how each package was installed. A catalog source indicates that the package was installed by consulting a package catalog. The name after catalog indicates the name of the package as requested from the catalog, which is normally (but not necessarily) the name of the package as it exists in your installation. We discuss other possibilities for “Source” in Installing Packages.

Neither the main-distribution package nor the racket-lib package actually provides any libraries on its own, but each declares dependencies on other packages. The racket-lib package depends on native-library packages, if any, for your platform. The main-distribution package depends on lots of packages that have been selected for inclusion in the main Racket distribution. If you provide the --all flag to raco pkg show, then you can see the packages that were automatically installed as a result of installing main-distribution and racket-lib (or whatever packages you have explicitly selected for your installation).

  raco pkg show --all

An asterisk appears beside the name of every package that was “auto-installed” to satisfy a dependency. All auto-installed packages are as available for your use in the same way as explicitly installed packages, but normally your code should refer only to packages that you have explicitly installed. The difference between an auto-installed and an explicitly installed package is how various commands, such as raco pkg show, treat the package. If you specifically request installation of a package that is auto-installed, then the package is promoted and thereafter treated as a explicitly installed package.

1.3 Finding Packages

The PLT package catalog at

http://pkgs.racket-lang.org

provides a centralized listing of available Racket packages. The PLT package catalog normally will be the first place you check when looking for a package.

There are other ways to distribute and reference packages. For example, a package can be installed directly from a ".zip" file—available locally or served from on a web site—or from a Github repository. Such direct references make sense when a package is not yet ready for wide distribution or when it will never be of interest to a wide audience. So, you may find non-catalog references in mailing-list posts, recommended by your friends, or advertised in e-mail spam.

There may be other package catalog services besides PLT’s. Note that even if you discover a package name from PLT’s package catalog, your installation may be configured to consult a different package catalog to locate the package’s implementation (to obtain a pre-built version of the package, for example), but you should expect the installation-configured package catalog to deliver the package that is described on the PLT package catalog.

1.4 Installing Packages

If you find a package by name from a package catalog, then use the package’s name with raco pkg install:

  raco pkg install pkg-name

If the package depends on other packages that you do not have installed already, then raco pkg install will alert you and ask whether it should install them, too. Use --auto to skip the question and make dependencies installed automatically. Either way, packages installed to satisfy dependencies are marked as auto-installed, which makes them easier to uninstall, and it also makes them hidden by default for raco pkg show (since packages that are installed for dependencies are an implementation detail that you usually do not care about).

The argument that you provide to raco pkg install does not have to be a package name that is recognized by a package catalog. In general, each argument to raco pkg install is a package source. A package source can refer to a ".zip" file, a ".tar" file, a Github repository, a directory-structured web site, or a few other possibilities. In each of those cases, a package name is inferred from the package source. After the package is installed, you use the package name with other raco pkg commands to refer to the installed package.

In fact, a package catalog does not actually serve package implementations. It simply maps each package name to a package source. When the package manager consults a package catalog, it gets back a package source for the actual package implementation, so each package installed from a package catalog is actually installed from a ".zip" file, Github repository, etc. Registering with a package catalog is just a way of making your package easier to find and update.

1.5 Updating Packages

If your package installations become out of date, you can update packages with raco pkg update:

  raco pkg update pkg-name

Either specify individual packages to update, or use --all to update all installed packages for which a new checksum is available.

The way that the package manager finds updates depends on the way that a package was installed. If it was installed by using a package name that was resolved by a package catalog, then the package catalog is consulted again to get the current checksum for the package, and the package is updated if the checksum doesn’t match the current installation. If the package was installed directly from a Github reference, then Github is consulted to get the current commit of a particular branch, and the package is updated if the commit identifier doesn’t match the checksum of the current installation.

In some cases, updating a package may require an update to one of the package’s dependencies. That should happen only when the package requires a new binding, feature, or bug fix from the dependent package, since packages are meant to evolve in an otherwise backward-compatible way. Package versions provide a way for package authors to declare (and for the package manager to check) those dependencies. The end result is that raco pkg update might report a version-mismatch error that forces you to request more package updates than you originally requested.

Normally, you provide package names to raco pkg update. More generally, you can provide a package source to raco pkg update. In that case, a package with the same name must be installed already, and the installed package is replaced with the specified one. Replacing a package with a new package source is a generalization of fetching a replacement package that has a new checksum at a previously specified source.

1.6 Removing Packages

As you might expect, raco pkg remove removes a package:

  raco pkg remove pkg-name

If the installation of a package triggered auto-installs of other packages, then removing the package does not automatically remove the auto-installed packages. Supply the --auto flag for raco pkg remove, either by itself or when uninstalling packages, to also remove any auto-installed packages that are left without dependents.

The raco pkg remove command will not remove a package if other installed packages depend on it, unless you force the removal. If you want to demote a package from explicitly installed to auto-installed (for clean-up later, perhaps when other packages are removed), then supply the --demote flag to raco pkg remove.

1.7 Creating Packages

A package normally starts life as a directory containing module files and grows up to become a Github repository that is registered with a package catalog.

So, to create a package, first make a directory and select its name, pkg-name:

  mkdir pkg-name

Although a package can provide libraries in any number of collections, it’s common for a package to provide only libraries in a collection that matches the package name. If that’s the case for your package, then files implementing modules in the pkg-name collection will go directly in the pkg-name directory that you have created.

If your package implements multiple collections, then you’ll need to add a basic "info.rkt" file in the pkg-name directory:

  cd pkg-name
  echo "#lang info" > info.rkt
  echo "(define collection 'multi)" >> info.rkt

The collection definition tells the package manager that the package implements libraries in multiple collections, and each collection is represented by a sub-directory whose name matches the collection name. Libraries for each collection go in the collection’s directory.

You can start with a single-collection package and later change it to a multi-collection package by restructuring the package directory, so you don’t have to worry much about the choice when you get started.

Whether creating a single-collection package or a multi-collection package, the next step is to link your development directory as a locally installed package. Use raco pkg install in the pkg-name directory:

  raco pkg install

If you use raco pkg show at this point, you’ll see a line for pkg-name. The “Source” column will show that it’s a linked package, and the “Checksum” column will say #f, which means that there is no checksum. Sub-commands like raco pkg update will not work on a linked package, because “updates” to the package happen whenever you modify the package’s implementation.

Finally, inside the pkg-name directory, add directories and/or files to implement the collections and/or modules that your package provides. For example, the developer of a tic-tac-toe multi-collection package that provides games/tic-tac-toe/main and data/matrix libraries might create directories and files like this:

  mkdir -p games/tic-tac-toe
  touch games/tic-tac-toe/info.rkt
  touch games/tic-tac-toe/main.rkt
  mkdir -p data
  touch data/matrix.rkt

An "info.rkt" file is not necessary for a single-collection package with no dependencies, but you may wish to create one, anyway, to hold dependency declarations. Every package at least depends on base, which provides the collections and libraries of a minimal Racket installation. To make your package work best for other users, you will ultimately need to declare all dependencies. (Fortunately, raco setup can check dependencies and help you figure out what dependencies to declare.)

Even for a single-collection package, you may want to create "info.rkt" and include the definition

(define collection "pkg-name")

This definition may seem redundant, since pkg-name is available as the name of the enclosing directory, but declaring the collection name explicitly prevents the meaning of your package’s implementation from depending on the way that the implementation is referenced.

Finally, in the case of a multi-collection package, note that the "info.rkt" file in pkg-name is for the package, not for a collection. Definitions such as scribblings or raco-commands work only in a collection’s "info.rkt". For a single-collection package, the "info.rkt" file serves double-duty for the package and collection.

1.8 Sharing Packages

After your package is ready to deploy, choose either GitHub Deployment or Manual Deployment, and then go on to Helping Others Discover Your Package.

1.8.1 GitHub Deployment

First, create a free account on GitHub, then create a repository for your package. After that, your package source is:

git://github.com/user/package

If you want the package to be branch instead of master, then add "#branch" to the end of the package source.

Whenever you

  git push

your changes will automatically be discovered by those who use raco pkg update after installing from your github-based package source.

1.8.2 Manual Deployment

Alternatively, you can deploy your package by publishing it on a URL you control. If you do this, it is preferable to create an archive from your package directory first:

  raco pkg create package

Then, upload the archive and its checksum to your site:

  scp package.zip package.zip.CHECKSUM your-host:public_html/

Your package source is then something like

http://your-host/~user/package.zip

Whenever you want to provide a new release of a package, recreate and reupload the package archive (and checksum). Your changes will automatically be discovered by those who used your package source when they use raco pkg update.

By default, raco pkg create generates a ".zip" archive. For more options, refer to the raco pkg create documentation. If you want to generate an archive through some other means, simply archive what you made in the first part of this section. For more formal details, refer to the package definition.

1.8.3 Helping Others Discover Your Package

By using either GitHub Deployment or Manual Deployment, anyone will be able to install your package by referring to your package source. However, they will not be able to refer to it by a simple name until it is listed on a package catalog.

If you’d like to use the PLT package catalog, browse to http://pkgs.racket-lang.org/ and upload a new package. You will need to create an account and log in first.

You only need to go to this site once to list your package. The server will periodically check the package source you designate for updates.

If you use this server, and if you use GitHub for deployment, then you will never need to open a web browser to update your package for end users. You just need to push to your GitHub repository, then within 24 hours, the PLT package catalog will notice, and raco pkg update will work on your user’s machines.

1.8.4 Naming and Designing Packages

We suggest the following conventions for naming and designing packages:

1.8.5 Packages Compatible with Racket 5.3.5 and 5.3.6

A beta version of the package system was added to Racket starting in version 5.3.5. By the time version 6.0 was released, some features were added.

By using only certain older features, it is possible to make a package that can be used with Racket versions 5.3.5, 5.3.6, 6.0, and newer.

In your info.rkt, you should:

Finally, when listing your package on http://pkgs.racket-lang-org, you should supply a GitHub source using the URL format github://github.com/user/repo/rev[/path] (not the git: format).