How to switch Rust toolchains with rustup

Rust projects often move between the stable compiler, the next beta, a nightly snapshot, or an older release while the same Cargo commands stay in use. rustup handles that selection through toolchain proxies, so developers can test a compiler boundary without replacing the whole Rust installation.

The smallest switch is a +toolchain prefix on one command. A project-local switch uses a rustup directory override, and a user-wide switch changes the default toolchain for directories that do not have an override or toolchain file.

Directory overrides are local rustup state, not files committed with the project. Use a committed rust-toolchain.toml when every contributor should inherit the same compiler choice, and use a rustup override when the change is only for your user account or a temporary compatibility check.

Steps to switch Rust toolchains with rustup:

Change into the Cargo project directory that should be tested or overridden.
```
$ cd /work/hello-rust
```
Use the directory that contains the project Cargo.toml. If a project does not exist yet, create one first.
Related: How to create a Rust project with Cargo

Install the target toolchain if it is not already installed.

$ rustup toolchain install beta --profile minimal
info: syncing channel updates for beta-aarch64-unknown-linux-gnu
info: latest update on 2026-06-13 for version 1.97.0-beta.4 (36645eb0d 2026-06-12)
info: downloading 3 components

  beta-aarch64-unknown-linux-gnu installed - rustc 1.97.0-beta.4 (36645eb0d 2026-06-12)

info: checking for self-update (current version: 1.29.0)

Replace beta with nightly, a version such as 1.85.0, or another installed toolchain name. The host triple in the output follows the local system.

List installed toolchains and confirm the target appears.

$ rustup toolchain list
stable-aarch64-unknown-linux-gnu (active, default)
beta-aarch64-unknown-linux-gnu

Run one Cargo command with the target toolchain.
```
$ cargo +beta check
    Checking hello-rust v0.1.0 (/work/hello-rust)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.12s
```
The +beta prefix affects only that one invocation. The default and any saved project override stay unchanged.
Set a project-local directory override when the project should keep using the target toolchain for normal Cargo commands.
```
$ rustup override set beta
info: override toolchain for /work/hello-rust set to beta-aarch64-unknown-linux-gnu
```
A rustup directory override applies to the current directory and its child directories until it is unset. Use rustup override unset from the project directory when the project should follow the default toolchain again.

Check the active toolchain inside the project directory.

$ rustup show active-toolchain
beta-aarch64-unknown-linux-gnu (directory override for '/work/hello-rust')

Run Cargo without the +beta prefix to confirm the directory override is active.

$ cargo check
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.01s

Inspect saved directory overrides when the selected toolchain is surprising.
```
$ rustup override list
/work/hello-rust                         beta-aarch64-unknown-linux-gnu
```
Override entries are stored in rustup user configuration, so they do not appear in git status or travel with the project repository.

Change the default user toolchain only when the target should apply outside project overrides.

$ rustup default beta
info: using existing install for beta-aarch64-unknown-linux-gnu
info: default toolchain set to beta-aarch64-unknown-linux-gnu

  beta-aarch64-unknown-linux-gnu unchanged - rustc 1.97.0-beta.4 (36645eb0d 2026-06-12)

info: note that the toolchain 'beta-aarch64-unknown-linux-gnu' is currently in use (directory override for '/work/hello-rust')

A directory override still wins inside that project. New shells or other directories without overrides use the default toolchain.

Print the default toolchain after the switch.

$ rustup default
beta-aarch64-unknown-linux-gnu (default)