Documentation🔗

rackup install🔗

Install a Racket toolchain from official release, pre-release, or snapshot installers.

rackup install <spec> [flags]

rackup list🔗

List installed toolchains and show default/active tags.

rackup list [--ids]

Output shows each toolchain’s ID, resolved version, variant, and distribution. Tags like [default] and [active] indicate the global default and the currently active toolchain (set via rackup switch or RACKUP_TOOLCHAIN).

rackup available🔗

List install aliases (stable, pre-release, snapshot) and numeric release versions. This queries the Racket download server for the full list of published releases.

rackup available [--all|--limit N]

rackup default🔗

Show, set, or clear the global default toolchain. The default determines which toolchain the shims use when no per-shell override (RACKUP_TOOLCHAIN) is active. If the requested toolchain spec is not installed, interactive shells are prompted to install it.

rackup default [id|status|set <toolchain>|clear|<toolchain>|--unset]

rackup current🔗

Show the active toolchain and whether it comes from shell activation (RACKUP_TOOLCHAIN) or the global default.

rackup current [id|source|line]

rackup which🔗

Show the real executable path for a tool in a toolchain. Without --toolchain, uses the active toolchain.

rackup which <exe> [--toolchain <toolchain>]

rackup switch🔗

Switch the active toolchain in the current shell without changing the global default. When run via the shell integration installed by rackup init, this updates the current shell’s environment immediately. Otherwise, it emits shell code that you can eval.

rackup switch <toolchain> | rackup switch --unset

If the requested toolchain is not installed, you are prompted to install it.

rackup shell🔗

Emit shell code to activate or deactivate a toolchain in the current shell. This is the low-level primitive used by rackup switch and the shell wrapper function. Most users should use rackup switch instead.

rackup shell <toolchain> | rackup shell --deactivate

rackup run🔗

Run a command under a specific toolchain without changing defaults or the shell environment. Sets PLTHOME, PLTADDONDIR, PATH, and RACKUP_TOOLCHAIN for the subprocess only.

rackup run <toolchain> -- <command> [args...]

The -- separator is required between the toolchain spec and the command to run.

rackup link🔗

Link an in-place or locally built Racket tree as a managed toolchain. The linked directory is not copied; rackup creates a symlink and metadata so that shims and rackup switch work with it.

rackup link <name> <path> [--set-default] [--force]

rackup remove🔗

Remove one installed or linked toolchain and its per-toolchain addon directory. For linked toolchains, only the rackup metadata and symlink are removed; the original source tree is untouched. Shims are rebuilt automatically afterward.

rackup remove <toolchain>

Also removes orphan/partial toolchain directories that were left behind by interrupted installs.

rackup prompt🔗

Print prompt/status information for the active toolchain. Designed to be called from PS1 or a prompt function. Prints nothing when no active/default toolchain is configured. When shell integration is active, the shell wrapper handles this without starting Racket for speed.

rackup prompt [--long|--short|--raw|--source]

rackup reshim🔗

Rebuild shim executables from the union of all installed toolchain executables. This runs automatically on install, link, remove, and default set, but can be run manually if shims get out of sync.

rackup reshim

Shims are small scripts placed in ~/.rackup/shims/ that delegate to the active toolchain’s real executable. Common shims include racket, raco, scribble, drracket, slideshow, gracket, mzscheme, and mzc.

rackup init🔗

Install or update shell integration in ~/.bashrc or ~/.zshrc. Writes a managed block that sources ~/.rackup/shell/rackup.<shell>. The managed block adds the shims directory to PATH and defines the rackup shell function that wraps rackup switch so it takes effect in the current shell.

rackup init [--shell bash|zsh]

If --shell is omitted, the current shell is detected automatically.

rackup self-upgrade🔗

Upgrade rackup’s own code by rerunning the bootstrap installer into the current RACKUP_HOME. By default this skips shell init edits and keeps your current shell config unchanged. The installer picks the best mode automatically (prebuilt binary if available for the current platform, otherwise source).

rackup self-upgrade [--with-init] [--exe | --source]

rackup runtime🔗

Manage rackup’s internal Racket runtime.

When rackup is installed from source, it uses a hidden minimal Racket installation to run itself. This runtime is separate from user toolchains and is not exposed via shims or PATH.

When rackup is installed as a prebuilt executable, Racket is embedded in the rackup-core binary and no hidden runtime is needed. In this mode, runtime install and runtime upgrade are no-ops; use rackup self-upgrade to update the executable instead.

rackup runtime status|install|upgrade

rackup uninstall🔗

Remove all rackup-managed data and shell init blocks. This is destructive and cannot be undone.

rackup uninstall [--yes]

rackup doctor🔗

Print diagnostics for rackup paths, hidden runtime, and installed toolchains. Useful when troubleshooting installation or shim issues. Reports on:

• RACKUP_HOME location and contents.

• Hidden runtime status and version.

• Installed toolchains, their metadata, and whether their directories exist.

• Shim directory contents and PATH status.

rackup doctor

rackup version🔗

Print rackup version information (git commit hash and date).

rackup version

Shell integration🔗

After the initial bootstrap, run rackup init to set up your shell. This adds a small managed block to your .bashrc or .zshrc that:

• Adds ~/.rackup/shims to PATH so racket, raco, etc. resolve to rackup shims.

• Defines a rackup shell function that wraps the real rackup binary. When you run rackup switch, the wrapper evals the emitted shell code so the switch takes effect in the current shell, without starting a subshell.

rackup init --shell bash   # or zsh

Once initialized, switching toolchains takes effect immediately:

$ rackup switch 8.18

$ racket --version           # uses 8.18

$ rackup switch stable

$ racket --version           # back to stable

The managed block is delimited by marker comments so that rackup init can update it idempotently and rackup uninstall can remove it cleanly.

Environment variables🔗

Directory layout🔗

All rackup state lives under RACKUP_HOME (default ~/.rackup). The layout differs slightly depending on how rackup was installed.

Toolchain resolution🔗

The active toolchain is resolved in this order:

1. RACKUP_TOOLCHAIN environment variable (set by rackup switch).

2. The global default (set by rackup default).

When you run a shimmed command like racket, the shim looks up the active toolchain, resolves its PLTHOME, and execs the real binary from the toolchain’s bin/ directory.

Migrating from racket-dev-goodies🔗

If you previously used racket-dev-goodies (the plt shell function and plt-bin symlinks), rackup replaces it entirely.

1. Remove the plt-alias.bash source line from your .bashrc/.zshrc and remove any plt-bin symlinks from your PATH. The plt function sets PLTHOME globally, which conflicts with rackup’s per-toolchain environment management.

2. Install rackup and re-register your Racket builds:

rackup link dev ~/src/racket

rackup link 8.15 /usr/local/racket-8.15

rackup default set dev

For release versions you can also use rackup install:

rackup install stable

rackup install 8.15

If you used the short r and dr aliases from racket-dev-goodies, enable them in rackup with:

rackup reshim --short-aliases

This creates r (for racket) and dr (for drracket) shims. You can also pass –short-aliases to rackup install.