Overrides
rustup
automatically determines which toolchain to use when one of the
installed commands like rustc
is executed. There are several ways to control
and override which toolchain is used:
- A toolchain override shorthand used on the command-line, such as
cargo +beta
. - The
RUSTUP_TOOLCHAIN
environment variable. - A directory override, set with the
rustup override
command. - The
rust-toolchain.toml
file. - The default toolchain.
The toolchain is chosen in the order listed above, using the first one that is
specified. There is one exception though: directory overrides and the
rust-toolchain.toml
file are also preferred by their proximity to the current
directory. That is, these two override methods are discovered by walking up
the directory tree toward the filesystem root, and a rust-toolchain.toml
file
that is closer to the current directory will be preferred over a directory
override that is further away.
To verify which toolchain is active, you can use rustup show
,
which will also try to install the corresponding
toolchain if the current one has not been installed according to the above rules.
(Please note that this behavior is subject to change, as detailed in issue #1397.)
Toolchain override shorthand
The rustup
toolchain proxies can be instructed directly to use a specific
toolchain, a convenience for developers who often test different toolchains.
If the first argument to cargo
, rustc
or other tools in the toolchain
begins with +
, it will be interpreted as a rustup
toolchain name, and that
toolchain will be preferred, as in
cargo +beta test
Directory overrides
Directories can be assigned their own Rust toolchain with rustup override
.
When a directory has an override then any time rustc
or cargo
is run
inside that directory, or one of its child directories, the override toolchain
will be invoked.
To use to a specific nightly for a directory:
rustup override set nightly-2014-12-18
Or a specific stable release:
rustup override set 1.0.0
To see the active toolchain use rustup show
. To remove the override and use
the default toolchain again, rustup override unset
.
The per-directory overrides are stored in a configuration file in rustup
's
home directory.
The toolchain file
Some projects find themselves 'pinned' to a specific release of Rust and want this information reflected in their source repository. This is most often the case for nightly-only software that pins to a revision from the release archives.
In these cases the toolchain can be named in the project's directory in a file
called rust-toolchain.toml
or rust-toolchain
. If both files are present in
a directory, the latter is used for backwards compatibility. The files use the
TOML format and have the following layout:
[toolchain]
channel = "nightly-2020-07-10"
components = [ "rustfmt", "rustc-dev" ]
targets = [ "wasm32-unknown-unknown", "thumbv2-none-eabi" ]
profile = "minimal"
The [toolchain]
section is mandatory, and at least one property must be
specified. channel
and path
are mutually exclusive.
For backwards compatibility, rust-toolchain
files also support a legacy
format that only contains a toolchain name without any TOML encoding, e.g.
just nightly-2021-01-21
. The file has to be encoded in US-ASCII in this case
(if you are on Windows, check the encoding and that it does not start with a
BOM). The legacy format is not available in rust-toolchain.toml
files.
If you see the following error (when running rustc
, cargo
or other command)
error: invalid channel name '[toolchain]' in '/PATH/TO/DIRECTORY/rust-toolchain'
it means you're running rustup
pre-1.23.0 and trying to interact with a project
that uses the new TOML encoding in the rust-toolchain
file. You need to upgrade
rustup
to 1.23.0+.
The rust-toolchain.toml
/rust-toolchain
files are suitable to check in to
source control.
The toolchains named in these files have a more restricted form than rustup
toolchains generally, and may only contain the names of the three release
channels, 'stable', 'beta', 'nightly', Rust version numbers, like '1.0.0', and
optionally an archive date, like 'nightly-2017-01-01'. They may not name
custom toolchains, nor host-specific toolchains. To use a custom local
toolchain, you can instead use a path
toolchain:
[toolchain]
path = "/path/to/local/toolchain"
Since a path
directive directly names a local toolchain, other options
like components
, targets
, and profile
have no effect. channel
and path
are mutually exclusive, since a path
already points to a
specific toolchain. A relative path
is resolved relative to the
location of the rust-toolchain.toml
file.
Default toolchain
If no other overrides are set, the global default toolchain will be used. This
default can be chosen when rustup
is installed. The rustup default
command can be used to set and query the current default. Run rustup default
without any arguments to print the current default. Specify a toolchain as an
argument to change the default:
rustup default nightly-2020-07-27