Install Rust with rustup and pin a toolchain

The computer these sessions ran on has three Rust toolchainstoolchain: One installed release of Rust's tools for one host: rustc, Cargo and the standard library, plus components such as rustfmt and Clippy. rustup names toolchains such as stable-aarch64-apple-darwin or 1.99.0-aarch64-apple-darwin. installed side by side, and the same command, rustc --version, answers 1.98.0 in one folder and 1.99.0 in another. Nothing is broken: rustuprustup: The installer and manager of Rust toolchains. Its commands in ~/.cargo/bin, cargo and rustc among them, are proxies that choose a toolchain for each run and hand the command to that toolchain's own program., the installer, chooses a toolchain for every command, and one small file in a project decides which.

This lesson installs Rust with rustup, reads what it installed, explains the stable, beta and nightly channels, and follows the fixed order in which rustup chooses a toolchain. Then you pin a project to Rust 1.99.0, with the componentscomponent: A part of a toolchain that rustup adds or removes on its own, such as clippy, rustfmt, rust-docs, rust-src or rust-analyzer, or the standard library for one target. and targetstarget: The kind of system a program is built for, named by a triple such as aarch64-apple-darwin, x86_64-pc-windows-msvc or wasm32-wasip1. Building for a target needs that target's standard library. it needs, so that every computer that builds it uses the same compiler.

rustup installs Rust, and every tool comes from a toolchain

On macOS and Linux, the install page of rust-lang.org gives one command, which downloads rustup’s installer and runs it: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh. On Windows you download and run rustup-init.exe instead, and you may be asked to install the Visual Studio C++ build tools first. Either way, the installer puts its commands in ~/.cargo/bin (%USERPROFILE%\.cargo\bin on Windows), tries to add that folder to your PATH, and keeps the toolchains in ~/.rustup. Open a new terminal afterwards, because the PATH change may not reach the one you have open.

Rust also needs a linker, the program that joins compiled pieces into one executable, and it uses the system’s. The Rust book’s advice for linker errors is to install a C compiler, which typically includes one: on macOS run xcode-select --install, on Linux install GCC or Clang (on Ubuntu, the build-essential package), and on Windows accept the Visual Studio installer when it is offered.

What rustup installs is a toolchain: one release of rustc, cargo and the standard library for your computer, plus extra tools as components. The default profile adds rust-docs, rustfmt and clippy to the three essentials; the minimal profile installs only rustc, rust-std and cargo, which is why some installs have no cargo fmt. Here is what this computer reports, run in its home folder:

from session import run

# In the home folder, where no toolchain file applies: what rustup has installed, and what runs by default.
run("""
rustup --version
rustup show
rustc --version
cargo --version
""")

$ rustup --version
rustup 1.29.1 (d95a37b6a)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: the currently active `rustc` version is `rustc 1.98.0 (88d9e12ae)`
$ rustup show
Default host: aarch64-apple-darwin
rustup home:  ~/.rustup

installed toolchains
--------------------
stable-aarch64-apple-darwin (active, default)
nightly-aarch64-apple-darwin
1.99.0-aarch64-apple-darwin

active toolchain
----------------
name: stable-aarch64-apple-darwin
active because: it's the default toolchain
installed targets:
  aarch64-apple-darwin
$ rustc --version
rustc 1.98.0 (88d9e12ae)
$ cargo --version
cargo 1.98.0 (797e8a9bc)

Three toolchains are installed: stable, nightly and the exact release 1.99.0. The default is stable, and on this computer stable is still 1.98.0, because rustup update has not been run on it since 1.99.0 came out. That is the first reason to pin a project: “stable” means whatever stable you installed last. The commands themselves are not the compilers: the cargo and rustc in ~/.cargo/bin are proxies of rustup, small programs that hand each command to the real toolchain. Step through one command:

Stable, beta and nightly: three channels for three needs

rustup installs toolchains from three release channelsrelease channel: A stream of Rust releases: stable, a new release every six weeks; beta, the next stable release while it is tested; and nightly, built every night with features that are not finished yet.. Each answers a different need:

A toolchain can be named by its channel (stable, beta, nightly) or by an exact release (1.99.0), and a +toolchain argument picks one for a single command. Here the three installed toolchains answer one after the other, and then the stable 1.99.0 and the nightly compile a file that uses an unfinished feature, try blocks:

// try blocks are an unfinished feature: only a nightly compiler accepts the #![feature] line.
#![feature(try_blocks)]

fn main() {
    let total: Option<u32> = try { "40".parse::<u32>().ok()? + "25".parse::<u32>().ok()? };
    println!("{total:?}");
}

from session import run

# One computer, three toolchains: a +toolchain argument picks one for a single command.
run("""
rustc +stable --version
rustc +1.99.0 --version
rustc +nightly --version
!rustc +1.99.0 --edition 2024 gated.rs
rustc +nightly --edition 2024 gated.rs
./gated
""")

$ rustc +stable --version
rustc 1.98.0 (88d9e12ae)
$ rustc +1.99.0 --version
rustc 1.99.0 (b940084d7)
$ rustc +nightly --version
rustc 1.101.0-nightly (0abfedbc7)
$ rustc +1.99.0 --edition 2024 gated.rs
error[E0554]: `#![feature]` may not be used on the stable release channel
 --> gated.rs:2:1
  |
2 | #![feature(try_blocks)]
  | ^^^^^^^^^^^^^^^^^^^^^^^

error: aborting due to 1 previous error

For more information about this error, try `rustc --explain E0554`.
[exit status 1]
$ rustc +nightly --edition 2024 gated.rs
$ ./gated
Some(65)

Stable Rust refused the #![feature(try_blocks)] line with error E0554: feature flags “may not be used on the stable release channel”. The nightly compiler accepted it, and the program printed Some(65). This is the rule the Rust book states: to try a feature that is still being worked on, you must use a nightly release and opt in with a flag in your code, while on stable and beta no feature flags are allowed.

rustup chooses the toolchain in a fixed order

Each time you run cargo, rustc or another of its commands, rustup looks for a choice in this order and uses the first one it finds, as its book’s chapter on overrides describes:

1. a +toolchain argument on the command line, such as cargo +beta test;
2. the RUSTUP_TOOLCHAIN environment variable;
3. a directory override, set with rustup override set for a folder and the folders inside it;
4. a rust-toolchain.toml file in the current folder or one above it;
5. the default toolchain, set with rustup default.

Step through four commands and watch each one stop at the first stage that names a toolchain:

These are the same four commands, run in this computer’s home folder and in ~/pinned, a folder that holds a toolchain file:

from session import run

# The same question in two folders, and two ways to overrule the toolchain file for one command.
run("""
rustup show active-toolchain
cd pinned
rustup show active-toolchain
rustc --version
rustc +stable --version
RUSTUP_TOOLCHAIN=nightly rustc --version
rustup override list
""")

$ rustup show active-toolchain
stable-aarch64-apple-darwin (default)
$ cd pinned
$ rustup show active-toolchain
1.99.0-aarch64-apple-darwin (overridden by '~/pinned/rust-toolchain.toml')
$ rustc --version
rustc 1.99.0 (b940084d7)
$ rustc +stable --version
rustc 1.98.0 (88d9e12ae)
$ RUSTUP_TOOLCHAIN=nightly rustc --version
rustc 1.101.0-nightly (0abfedbc7)
$ rustup override list
no overrides

rustup show active-toolchain names the toolchain and the reason, which makes it the first command to run when a build behaves differently on two computers. In the home folder the default answered; in ~/pinned the file did, and both +stable and the environment variable overruled the file for one command. rustup override list found no directory overrides. An override is kept in rustup’s own settings on one computer, so it is handy for an experiment, while a toolchain file lives in the project and travels with it to every computer and to CI.

A rust-toolchain.toml pins the release, its components and its targets

A project is pinned by one file in its top folder. This one names the exact release, two components that every build of the project needs, and one extra target, WebAssembly with WASI, for which the standard library must be installed:

[toolchain]
channel = "1.99.0"
components = ["clippy", "rustfmt"]
targets = ["wasm32-wasip1"]

Commit the file with the code. Any computer that builds the project then uses Rust 1.99.0, and if that toolchain is not installed yet, rustup installs it on the first command, because automatic installation is on by default (RUSTUP_AUTO_INSTALL=1). Here is what the file selects in ~/pinned:

from session import run

# What the pinned folder's toolchain holds: the file, the toolchain it selects, its components and targets.
run("""
cd pinned
cat rust-toolchain.toml
rustup show
rustup component list --installed
!rustup doc --path
""")

$ cd pinned
$ cat rust-toolchain.toml
[toolchain]
channel = "1.99.0"
components = ["clippy", "rustfmt"]
targets = ["wasm32-wasip1"]
$ rustup show
Default host: aarch64-apple-darwin
rustup home:  ~/.rustup

installed toolchains
--------------------
stable-aarch64-apple-darwin (default)
nightly-aarch64-apple-darwin
1.99.0-aarch64-apple-darwin (active)

active toolchain
----------------
name: 1.99.0-aarch64-apple-darwin
active because: overridden by '~/pinned/rust-toolchain.toml'
installed targets:
  aarch64-apple-darwin
  thumbv7m-none-eabi
  wasm32-unknown-unknown
  wasm32-wasip1
  wasm32-wasip2
$ rustup component list --installed
cargo-aarch64-apple-darwin
clippy-aarch64-apple-darwin
rust-src
rust-std-aarch64-apple-darwin
rust-std-thumbv7m-none-eabi
rust-std-wasm32-unknown-unknown
rust-std-wasm32-wasip1
rust-std-wasm32-wasip2
rustc-aarch64-apple-darwin
rustfmt-aarch64-apple-darwin
$ rustup doc --path
info: `rust-docs` not installed in toolchain `1.99.0-aarch64-apple-darwin`
help: run `rustup component add --toolchain 1.99.0-aarch64-apple-darwin rust-docs` to install it
error: unable to view documentation which is not installed
[exit status 1]

The active toolchain is 1.99.0, “overridden by” the file. Its components include clippy and rustfmt, which the file asks for, and rust-src, the standard library’s source code, but not rust-docs, so rustup doc cannot open the offline documentation until rustup component add rust-docs installs it: the help line says exactly that. The installed targets are the host, aarch64-apple-darwin, plus four that were added to this toolchain, wasm32-wasip1 among them.

A target is named by a triple such as aarch64-apple-darwin: the processor, the vendor and the operating system. Rust’s platform support page sorts targets into tiers by what the project promises for them:

• Tier 1 with host tools, “guaranteed to work” and tested on every change: eight targets, among them aarch64-apple-darwin, x86_64-unknown-linux-gnu and x86_64-pc-windows-msvc.
• Tier 2 with host tools, “guaranteed to build”, with the compiler itself available there: among others x86_64-apple-darwin, Macs with Intel processors.
• Tier 2, “guaranteed to build”, for compiling from another computer: wasm32-wasip1 for WebAssembly and thumbv7m-none-eabi for Cortex-M chips, which has no std, only the core and alloc parts of the standard library.

The toolchain file says which compiler builds the project. A package can also say which is the oldest release it supports, with rust-version in its Cargo.toml, and Cargo then refuses an older compiler with a clear message instead of a confusing error later:

from session import run

# A package that says it needs Rust 1.99 or later, built with the pinned 1.99.0 and then with this computer's stable.
run("""
cd pinned/canteen
cat Cargo.toml
cargo run
!cargo +stable run
""")

$ cd pinned/canteen
$ cat Cargo.toml
[package]
name = "canteen"
version = "0.1.0"
edition = "2024"
rust-version = "1.99"

[dependencies]
$ cargo run
   Compiling canteen v0.1.0 (~/pinned/canteen)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in …
     Running `target/debug/canteen`
canteen built with a Rust new enough for it
$ cargo +stable run
error: rustc 1.98.0 is not supported by the following package:
  canteen@0.1.0 requires rustc 1.99
[exit status 101]

With the pinned 1.99.0 the package built and ran. With +stable, this computer’s 1.98.0, Cargo stopped before compiling anything: rustc 1.98.0 “is not supported”, because canteen requires 1.99.

Practise: pin a project of your own

Make a folder for a project, and write a rust-toolchain.toml in it that pins Rust 1.99.0 with clippy, rustfmt and the wasm32-wasip1 target, like the file above. Then, in that folder, run rustup show active-toolchain and rustc --version, and compare with the session in the previous section: the first line should name 1.99.0-<your host>, overridden by your file, and the second rustc 1.99.0. If rustup starts downloading, the release or one of its parts was not installed yet, and the file is doing its job.

Then try the questions on channels, the order rustup follows and toolchain files. A wrong answer shows its reason straight away, and that idea comes back before the others:

Interview questions

Warm-up: what is the difference between rustup, rustc and cargo?

rustc is the Rust compiler: it turns source files into a library or an executable. Cargo is Rust’s build tool and package manager: it reads Cargo.toml, fetches dependencies, calls rustc with the right options for every crate, and runs tests, benchmarks and documentation builds. rustup is neither; it installs and manages toolchains, each one a release of rustc, Cargo and the standard library, and its proxies in ~/.cargo/bin decide which toolchain runs each command, from a +toolchain argument, RUSTUP_TOOLCHAIN, a directory override, a rust-toolchain.toml file or the default. A good answer adds the practical consequence: when a build behaves differently on two computers, rustup show active-toolchain and rustc --version show which compiler each one really uses.

Key takeaways

• rustup installs toolchains, each a release of rustc, cargo and the standard library, and its commands in ~/.cargo/bin start the toolchain that applies; Rust links with the system’s linker, so install one first.
• Stable ships every six weeks and is for all your work, beta is the next stable release to test against, and nightly is only for unfinished features, which stable refuses with E0554.
• rustup uses the first choice it finds: a +toolchain argument, RUSTUP_TOOLCHAIN, a directory override, a rust-toolchain.toml file, then the default, and rustup show active-toolchain says which one won.
• A committed rust-toolchain.toml pins the release, its components and its targets for every computer, while rust-version in Cargo.toml states the oldest release a package supports.