rgoussu.dev
rgoussu@goussu: ~/library/rust/toolchain
❯ ~/library/rust/toolchain cat rustup.md

rustup — toolchain management & the release channels

# The toolchain multiplexer — stable/beta/nightly channels, components, cross-compilation targets, and per-project pinning via rust-toolchain.toml.

Conceptsaved 2026-08-09updated 2026-08-20 #rust#tooling#rustup#toolchain

Overview

rustup is the official installer and version multiplexer: it installs toolchains (a compiler + stdlib + core tools for one channel and host triple), switches between them, adds optional components and cross-compilation targets, and shims cargo/rustc so the right toolchain answers per directory. It is the piece the Go world lacked until the 1.21 toolchain directive and the JVM world solves with third-party managers (SDKMAN!, jenv) — here it is first-party and assumed by all documentation.

Key points

  • Channels: stable (a release every six weeks), beta (the next stable, soaking), nightly (built daily, the only place #![feature(...)] gates work). Update all with rustup update.
  • The shims: ~/.cargo/bin/cargo and friends are rustup proxies that resolve which real toolchain to run — which is why rustup override, rust-toolchain.toml and cargo +nightly … all work without touching PATH.
  • rust-toolchain.toml at the repo root pins channel, components and targets for everyone who clones — the reproducibility move; teammates and CI get the exact toolchain automatically on first cargo invocation.
  • Components: rustfmt, clippy, rust-analyzer, miri (nightly only), rust-src (needed by rust-analyzer and -Zbuild-std), llvm-tools — added per toolchain with rustup component add.
  • Targets: rustup target add x86_64-unknown-linux-musl installs a pre-built standard library for another triple — half of Rust's cross-compilation story; the other half (a linker) is yours to provide.
  • Pinned toolchains: rustup toolchain install 1.85.0 and channel = "1.85.0" in rust-toolchain.toml — how MSRV-sensitive projects and reproducible builds pin exactly.
  • There is no "series" channel — and this bites anyone automating pins. A channel (stable) or an exact version (1.85.0) are the only two spellings; "latest 1.85.x" cannot be expressed. So a project wanting major-only pinning has to take stable, which floats across majors too, and accept that its Rust version is "current stable by construction" rather than a series it controls. Most other version managers resolve a prefix; rustup is the outlier.
  • rustup doc opens the offline copy of the book, reference and stdlib docs matching your installed version — underused and excellent on trains.

Examples

# rust-toolchain.toml — committed at the repo root
[toolchain]
channel = "1.85.0"
components = ["rustfmt", "clippy"]
targets = ["x86_64-unknown-linux-musl"]

rustup update                        # all installed toolchains
cargo +nightly expand                # one-off run on another toolchain
rustup component add miri --toolchain nightly
rustup target add wasm32-wasip1

Related

  • The Rust toolchain — parent catalog; where rustup sits in the whole picture.
  • How Rust evolves — the release train and feature gates the channels implement.
  • cargo — the tool the shims dispatch to.
  • Building & releasing — targets in anger: cross-compilation and static musl builds.
  • Version managers — rustup's place among the ecosystem-native managers, and the universal ones that can replace it.