Skip to content

carapace-sh/carapace-bin / skills/rustup

rustup

Verified

Use when working with the rustup CLI — the Rust toolchain multiplexer. Covers installing/updating/uninstalling toolchains, channel syntax (stable/beta/nightly, dated, versioned), cross-compilation targets, components and profiles, directory and file overrides (rust-toolchain.toml), the proxy/shim dispatch system (cargo/rustc/rustdoc/rustfmt/rust-analyzer), `rustup run`, `+toolchain` shorthand, self-management, shell completions, and environment variables. Triggers on: "rustup", "rustup install", "rustup update", "rustup toolchain", "rustup target", "rustup component", "rustup override", "rustup run", "rustup which", "rustup doc", "rustup man", "rustup self", "rustup show", "rustup set", "rustup home", "rustup completions", "rustup check", "rustup default", "+toolchain", "rust-toolchain.toml", "RUSTUP_HOME", "RUSTUP_TOOLCHAIN", "RUSTUP_AUTO_INSTALL", "rustup profile", "rustup proxy", "rust-analyzer proxy", "cargo-miri".

FileKindSize
SKILL.mdskill md5.2 KB
references/cli.mdmarkdown7.1 KB
references/component.mdmarkdown3.9 KB
references/environment.mdmarkdown5.8 KB
references/override.mdmarkdown6.1 KB
references/proxy.mdmarkdown7.1 KB
references/target.mdmarkdown3.5 KB
references/toolchain.mdmarkdown4.9 KB

references/toolchain.md

View on GitHub
# Toolchain Management

How rustup manages toolchains — the `rustup toolchain` subcommands, the toolchain specification syntax, and custom toolchains.

## `rustup toolchain` Subcommands

| Subcommand | Description |
|------------|-------------|
| `rustup toolchain install <toolchain>` | Install a toolchain |
| `rustup toolchain uninstall <toolchain>...` | Uninstall one or more toolchains |
| `rustup toolchain remove <toolchain>...` | Alias for `uninstall` |
| `rustup toolchain list` | List installed toolchains |
| `rustup toolchain link <name> <path>` | Create a custom toolchain by linking to a local Rust build |

`rustup install` and `rustup uninstall` are shorthands for `rustup toolchain install` / `rustup toolchain uninstall` — they share the same flags.

### `toolchain install` flags

| Flag | Description |
|------|-------------|
| `--profile <name>` | Installation profile: `minimal`/`default`/`complete` — see [component.md](component.md) |
| `--component <name>` | Additional component to install (repeatable) |
| `--target <target>` | Additional target to install (repeatable) |
| `--force` | Force installation even if components are missing |
| `--allow-downgrade` | Allow rustup to downgrade to find required components |
| `--force-non-host` | Allow installing a non-host toolchain |
| `--no-self-update` | Suppress rustup self-update during install |

### `toolchain list` flags

| Flag | Description |
|------|-------------|
| `--verbose` / `-v` | Show rustc version info for each toolchain |
| `--quiet` / `-q` | Single-column output (useful for scripting) |

## Toolchain Specification Syntax

A toolchain name encodes a release channel, optional date, and optional host triple:

```
<channel>[-<date>][-<host>]
```

| Component | Form | Examples |
|-----------|------|----------|
| `<channel>` | `stable` \| `beta` \| `nightly` \| `<version>` | `stable`, `1.70.0`, `1.70` |
| `<version>` | `<major.minor>` \| `<major.minor.patch>` | `1.70`, `1.70.0` |
| `<date>` | `YYYY-MM-DD` | `2024-01-15` |
| `<host>` | target triple (or abbreviated on Windows) | `x86_64-pc-windows-msvc`, `msvc`, `gnu` |

### Examples

| Spec | Meaning |
|------|---------|
| `stable` | Latest stable release |
| `beta` | Latest beta release |
| `nightly` | Latest nightly build |
| `1.70.0` | Exact version 1.70.0 |
| `1.70` | Latest patch in the 1.70.x series |
| `nightly-2024-01-15` | Nightly from a specific date |
| `stable-x86_64-pc-windows-msvc` | Stable with full host triple |
| `stable-msvc` | Stable with abbreviated host (Windows MSVC ABI) |
| `stable-gnu` | Stable with GNU ABI on Windows |
| `nightly-2024-01-15-x86_64-pc-windows-msvc` | Full date + host |

### Versioned channels

- `1.70.0` pins to an exact patch release.
- `1.70` resolves to the latest patch release in the 1.70.x series.

### Dated toolchains

Dated toolchains are primarily used with the **nightly** channel to pin to a specific nightly build. This is common for projects that depend on unstable features available only on a particular nightly.

```
rustup install nightly-2024-01-15
rustup default nightly-2024-01-15
```

### Host triples

The host triple identifies the platform ABI. On Windows, abbreviated forms are accepted:

- `msvc` — expands to the host arch with the MSVC ABI (e.g. `x86_64-pc-windows-msvc`)
- `gnu` — expands to the host arch with the GNU ABI (e.g. `x86_64-pc-windows-gnu`)

On other platforms the host triple is typically omitted (rustup infers the host).

## Custom Toolchains

A custom toolchain is a locally-built Rust sysroot that rustup tracks by name. Create one with `rustup toolchain link`:

```
rustup toolchain link my-toolchain /path/to/rust/build/sysroot
```

- The `<path>` must point to a directory laid out like a standard Rust sysroot (containing `bin/`, `lib/`, etc.).
- rustup creates a directory symlink to `<path>` in `${RUSTUP_HOME}/toolchains/<name>`.
- Custom toolchains appear in `rustup toolchain list` and can be selected with `+my-toolchain`, `rustup default my-toolchain`, or `rustup run my-toolchain <cmd>`.
- Custom toolchains do not auto-update.

### Cargo fallback for custom toolchains

If a custom toolchain does not include `cargo`, rustup falls back to `cargo` from a release channel, preferring **nightly**, then **beta**, then **stable**.

## Where Toolchains Live

Installed toolchains are stored under `${RUSTUP_HOME}/toolchains/<toolchain-name>/`:

```
~/.rustup/toolchains/
  stable-x86_64-unknown-linux-gnu/
    bin/    # rustc, cargo, rustdoc, ...
    lib/    # std, libraries for the dynamic linker path
    share/  # documentation
  nightly-2024-01-15-x86_64-unknown-linux-gnu/
  my-toolchain -> /path/to/custom/sysroot
```

See [environment.md](environment.md) for `RUSTUP_HOME` configuration.

## Related

- [component.md](component.md) — components and profiles installed with a toolchain
- [target.md](target.md) — cross-compilation targets added to a toolchain
- [override.md](override.md) — how the active toolchain is selected
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall