rustup: the Rust toolchain installer
|Master CI||Build Status|
rustup installs The Rust Programming Language from the official release channels, enabling you to easily switch between stable, beta, and nightly compilers and keep them updated. It makes cross-compiling simpler with binary builds of the standard library for common platforms. And it runs on all platforms Rust supports, including Windows.
- How rustup works
- Keeping Rust up to date
- Working with nightly Rust
- Toolchain specification
- Toolchain override shorthand
- Directory overrides
- The toolchain file
- Override precedence
- Working with Rust on Windows
- Working with custom toolchains
- Working with network proxies
- Environment variables
- Other installation methods
rustup and other standard tools
bin directory. On Unix it is located at
$HOME/.cargo/bin and on Windows at
is the same directory that
cargo install will install Rust programs
and Cargo plugins.
This directory will be in your
$PATH environment variable, which
means you can run them from the shell without further
configuration. Open a new shell and type the following:
If you see something like
rustc 1.19.0 (0ade33941 2017-07-17) then
you are ready to Rust. If you decide Rust isn't your thing, you can
completely remove it from your system by running
rustup self uninstall.
rustup has the concept of "profiles". They are groups of components you can
choose to download while installing a new Rust toolchain. The profiles
available at this time are
- The minimal profile includes as few components as possible to get a
working compiler (
cargo). It's recommended to use this component on Windows systems if you don't use local documentation, and in CI.
- The default profile includes all the components previously installed by
clippy. This profile will be used by
rustupby default, and it's the one recommended for general use.
- The complete profile includes all the components available through
miriand IDE integration tools (
To change the
rustup profile you can use the
rustup set profile command. For
example, to select the minimal profile you can use:
rustup set profile minimal
It's also possible to choose the profile when installing
rustup for the first
time, either interactively by choosing the "Customize installation" option or
programmaticaly by passing the
--profile=<name> flag. Profiles will only
affect newly installed toolchains: as usual it will be possible to install
individual components later with:
rustup component add.
Enable tab completion for Bash, Fish, Zsh, or PowerShell
rustup now supports generating completion scripts for Bash, Fish,
Zsh, and PowerShell. See
rustup help completions for full details,
but the gist is as simple as using one of the following:
# Bash $ rustup completions bash > ~/.local/share/bash-completion/completions/rustup # Bash (macOS/Homebrew) $ rustup completions bash > $(brew --prefix)/etc/bash_completion.d/rustup.bash-completion # Fish $ mkdir -p ~/.config/fish/completions $ rustup completions fish > ~/.config/fish/completions/rustup.fish # Zsh $ rustup completions zsh > ~/.zfunc/_rustup # PowerShell v5.0+ $ rustup completions powershell >> $PROFILE.CurrentUserCurrentHost # or $ rustup completions powershell | Out-String | Invoke-Expression
Note: you may need to restart your shell in order for the changes to take effect.
zsh, you must then add the following line in your
Choosing where to install
rustup allows you to customise your installation by setting the environment
RUSTUP_HOME before running the
executable. As mentioned in the Environment Variables section,
sets the root
rustup folder, which is used for storing installed
toolchains and configuration options.
CARGO_HOME contains cache files used
Note that you will need to ensure these environment variables are always
set and that
CARGO_HOME/bin is in the
$PATH environment variable when
using the toolchain.
How rustup works
rustup is a toolchain multiplexer. It installs and manages many
Rust toolchains and presents them all through a single set of tools
cargo installed to
~/.cargo/bin are proxies that delegate to the real
rustup then provides mechanisms to easily change the
active toolchain by reconfiguring the behavior of the proxies.
rustup is first installed running
rustc will run the proxy
$HOME/.cargo/bin/rustc, which in turn will run the stable
compiler. If you later change the default toolchain to nightly with
rustup default nightly, then that same proxy will run the
Keeping Rust up to date
Rust is distributed on three different release channels: stable,
beta, and nightly.
rustup is configured to use the stable channel by
default, which represents the latest release of Rust,
and is released every six weeks.
When a new version of Rust is released, you can type
rustup update to update
$ rustup update info: syncing channel updates for 'stable' info: downloading component 'rustc' info: downloading component 'rust-std' info: downloading component 'rust-docs' info: downloading component 'cargo' info: installing component 'rustc' info: installing component 'rust-std' info: installing component 'rust-docs' info: installing component 'cargo' info: checking for self-updates info: downloading self-updates stable updated: rustc 1.7.0 (a5d1e7a59 2016-02-29)
This is the essence of
Keeping rustup up to date
rustup update also checks for updates to
rustup and automatically
installs the latest version. To manually check for updates and install the
latest version of
rustup without updating installed toolchains type
rustup self update:
$ rustup self update info: checking for self-updates info: downloading self-updates
rustup will automatically update itself at the end of any toolchain
installation as well. You can prevent this automatic behaviour by passing the
--no-self-update argument when running
rustup update or
rustup toolchain install.
Working with nightly Rust
rustup gives you easy access to the nightly compiler and its
experimental features. To add it just run
rustup toolchain install nightly:
$ rustup toolchain install nightly info: syncing channel updates for 'nightly' info: downloading toolchain manifest info: downloading component 'rustc' info: downloading component 'rust-std' info: downloading component 'rust-docs' info: downloading component 'cargo' info: installing component 'rustc' info: installing component 'rust-std' info: installing component 'rust-docs' info: installing component 'cargo' nightly installed: rustc 1.9.0-nightly (02310fd31 2016-03-19)
Now Rust nightly is installed, but not activated. To test it out you can run a command from the nightly toolchain like
$ rustup run nightly rustc --version rustc 1.9.0-nightly (02310fd31 2016-03-19)
But more likely you want to use it for a while. To switch to nightly
globally, change the default with
rustup default nightly:
$ rustup default nightly info: using existing install for 'nightly' info: default toolchain set to 'nightly' nightly unchanged: rustc 1.9.0-nightly (02310fd31 2016-03-19)
Now any time you run
rustc you will be running the
With nightly installed any time you run
rustup update, the nightly channel
will be updated in addition to stable:
$ rustup update info: syncing channel updates for 'stable' info: syncing channel updates for 'nightly' info: checking for self-updates info: downloading self-updates stable unchanged: rustc 1.7.0 (a5d1e7a59 2016-02-29) nightly unchanged: rustc 1.9.0-nightly (02310fd31 2016-03-19)
A note about nightly stability: Nightly toolchains may fail to build, so for
any given date and target platform there may not be a toolchain available.
Furthermore, nightly builds may be published with missing non-default components
clippy). As such, it can be difficult to find fully-working nightlies.
Use the rustup-components-history project to find the build status of
recent nightly toolchains and components.
rustup commands deal with toolchains, a single installation
of the Rust compiler.
rustup supports multiple types of
toolchains. The most basic track the official release channels:
stable, beta and nightly; but
rustup can also install
toolchains from the official archives, for alternate host platforms,
and from local builds.
Standard release channel toolchain names have the following form:
<channel>[-<date>][-<host>] <channel> = stable|beta|nightly|<version> <date> = YYYY-MM-DD <host> = <target-triple>
'channel' is either a named release channel or an explicit version number, such as '1.8.0'. Channel names can be optionally appended with an archive date, as in 'nightly-2014-12-18', in which case the toolchain is downloaded from the archive for that date.
Finally, the host may be specified as a target triple. This is most useful for installing a 32-bit compiler on a 64-bit platform, or for installing the MSVC-based toolchain on Windows. For example:
$ rustup toolchain install stable-x86_64-pc-windows-msvc
For convenience, elements of the target triple that are omitted will be inferred, so the above could be written:
$ rustup toolchain install stable-msvc
Toolchain names that don't name a channel instead can be used to name custom toolchains.
Toolchain override shorthand
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
other tools in the toolchain begins with
+, it will be interpreted
rustup toolchain name, and that toolchain will be preferred,
cargo +beta test
Directories can be assigned their own Rust toolchain with
rustup override. When a directory has an override then any time
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 toolchain file
rustup directory overrides are a local configuration, stored in
$RUSTUP_HOME. Some projects though 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, the content of which is the name of
rustup toolchain, and which is suitable to check in to
The toolchains named in this file 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
There are several ways to specify which toolchain
- An explicit toolchain, e.g.
- A directory override, ala
rustup override set beta,
- The default toolchain,
and they are preferred by
rustup in that order, with the explicit
toolchain having highest precedence, and the default toolchain having
the lowest. There is one exception though: directory overrides and the
rust-toolchain 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 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 use
Rust supports a great number of platforms. For many of these
platforms The Rust Project publishes binary releases of the standard
library, and for some the full compiler.
rustup gives easy access
to all of them.
When you first install a toolchain,
rustup installs only the
standard library for your host platform - that is, the architecture
and operating system you are presently running. To compile to other
platforms you must install other target platforms. This is done
rustup target add command. For example, to add the
$ rustup target add arm-linux-androideabi info: downloading component 'rust-std' for 'arm-linux-androideabi' info: installing component 'rust-std' for 'arm-linux-androideabi'
arm-linux-androideabi target installed you can then build
for Android with Cargo by passing the
--target flag, as in
cargo build --target=arm-linux-androideabi.
rustup target add only installs the Rust standard library
for a given target. There are typically other tools necessary to
cross-compile, particularly a linker. For example, to cross compile
to Android the Android NDK must be installed. In the future,
will provide assistance installing the NDK components as well.
To install a target for a toolchain that isn't the default toolchain
--toolchain argument of
rustup target add, like so:
$ rustup target add --toolchain <toolchain> <target>...
To see a list of available targets,
rustup target list. To remove a
rustup target remove.
Working with Rust on Windows
rustup works the same on Windows as it does on Unix, but there are
some special considerations for Rust developers on Windows. As
mentioned on the Rust download page, there are two ABIs in use
on Windows: the native (MSVC) ABI used by Visual Studio, and the GNU
ABI used by the GCC toolchain. Which version of Rust you need depends
largely on what C/C++ libraries you want to interoperate with: for
interop with software produced by Visual Studio use the MSVC build of
Rust; for interop with GNU software built using the MinGW/MSYS2
toolchain use the GNU build.
When targeting the MSVC ABI, Rust additionally requires an installation of Visual Studio 2013 (or later) or the Visual C++ Build Tools 2019 so rustc can use its linker. For Visual Studio, make sure to check the "C++ tools" and "Windows 10 SDK" option. No additional software installation is necessary for basic use of the GNU build.
rustup on Windows configures Rust to target the MSVC
ABI, that is a target triple of either
x86_64-pc-windows-msvc depending on the CPU architecture of the
host Windows OS. The toolchains that
rustup chooses to install, unless
told otherwise through the toolchain specification, will be compiled
to run on that target triple host and will target that triple by default.
You can change this behavior with
rustup set default-host or during installation.
For example, to explicitly select the 32-bit MSVC host:
$ rustup set default-host i686-pc-windows-msvc
Or to choose the 64 bit GNU toolchain:
$ rustup set default-host x86_64-pc-windows-gnu
Since the MSVC ABI provides the best interoperation with other Windows software
it is recommended for most purposes. The GNU toolchain is always available, even
if you don't use it by default. Just install it with
rustup toolchain install:
$ rustup toolchain install stable-gnu
You don't need to switch toolchains to support all windows targets though; a single toolchain supports all four x86 windows targets:
$ rustup target add x86_64-pc-windows-msvc $ rustup target add x86_64-pc-windows-gnu $ rustup target add i686-pc-windows-msvc $ rustup target add i686-pc-windows-gnu
Working with distribution Rust packages
Several Linux distributions package Rust, and you may wish to use the packaged
toolchain, such as for distribution package development. You may also wish to
rustup-managed toolchain such as nightly or beta. Normally,
will complain that you already have Rust installed in /usr and refuse to
install. However, you can install Rust via
rustup and have it coexist with
your distribution's packaged Rust.
When you initially install Rust with
rustup, pass the
-y option to make it
ignore the packaged Rust toolchain and install a
rustup-managed toolchain into
~/.cargo/bin. Add that directory to your
$PATH (or let
rustup do it for
you by not passing
--no-modify-path). Then, to tell
rustup about your system
rustup toolchain link system /usr
You can then use +system as a
rustup toolchain, just like +nightly; for
instance, you can run cargo +system build to build with the system toolchain,
or cargo +nightly build to build with nightly.
If you do distribution Rust development, you should likely make +system your default toolchain:
rustup default system
Working with custom toolchains and local builds
For convenience of developers working on Rust itself,
rustup can manage
local builds of the Rust toolchain. To teach
rustup about your build,
$ rustup toolchain link my-toolchain path/to/my/toolchain/sysroot
For example, on Ubuntu you might clone
~/rust, build it, and then run:
$ rustup toolchain link myrust ~/rust/build/x86_64-unknown-linux-gnu/stage2/ $ rustup default myrust
Now you can name
my-toolchain as any other
toolchain. Create a
rustup toolchain for each of your
rust-lang/rust workspaces and test them easily with
rustup run my-toolchain rustc.
rust-lang/rust tree does not include Cargo, when
is invoked for a custom toolchain and it is not available,
will attempt to use
cargo from one of the release channels,
preferring 'nightly', then 'beta' or 'stable'.
Working with network proxies
Enterprise networks often don't have direct outside HTTP access, but enforce
the use of proxies. If you're on such a network, you can request that
rustup uses a proxy by setting its URL in the environment. In most cases,
https_proxy should be sufficient. On a Unix-like system with a
shell like bash or zsh, you could use:
export https_proxy=socks5://proxy.example.com:1080 # or http://proxy.example.com:8080
On Windows, the command would be:
If you need a more complex setup,
rustup supports the convention used by
the curl program, documented in the ENVIRONMENT section of
its manual page.
The use of
curl is presently deprecated, however it can still be used by
RUSTUP_USE_CURL environment variable, for example:
RUSTUP_USE_CURL=1 rustup update
Note that some versions of
libcurl apparently require you to drop the
https:// prefix in environment variables. For example,
export http_proxy=proxy.example.com:1080 (and likewise for HTTPS).
If you are getting an SSL
unknown protocol error from
but the command-line
curl command works fine, this may be the problem.
||Set the default toolchain to the latest nightly|
||Set the default "profile" (see profiles)|
||List all available targets for the active toolchain|
||Install the Android target|
||Remove the Android target|
||Run the nightly regardless of the active toolchain|
||Shorthand way to run a nightly compiler|
||Run a shell configured for the nightly compiler|
||On Windows, use the MSVC toolchain instead of GNU|
||For the current directory, use a nightly from a specific date|
||Install a custom toolchain by symlinking an existing installation|
||Show which toolchain will be used in the current directory|
||Uninstall a given toolchain|
||(Unix only) View the man page for a given command (like
%USERPROFILE%/.rustup) Sets the root
rustupfolder, used for storing installed toolchains and configuration options.
RUSTUP_TOOLCHAIN(default: none) If set, will override the toolchain used for all rust tool invocations. A toolchain with this name should be installed, or invocations will fail.
https://static.rust-lang.org) Sets the root URL for downloading static resources related to Rust. You can change this to instead use a local mirror, or to test the binaries from the staging directory.
https://static.rust-lang.org/dist) Deprecated. Use
https://static.rust-lang.org/rustup) Sets the root URL for downloading self-updates.
RUSTUP_IO_THREADSunstable (defaults to reported cpu count). Sets the number of threads to perform close IO in. Set to
disabledto force single-threaded IO for troubleshooting, or an arbitrary number to override automatic detection.
RUSTUP_TRACE_DIRunstable (default: no tracing) Enables tracing and determines the directory that traces will be written too. Traces are of the form PID.trace. Traces can be read by the Catapult project tracing viewer.
RUSTUP_UNPACK_RAMunstable (default 400M, min 100M) Caps the amount of RAM
rustupwill use for IO tasks while unpacking.
RUSTUP_NO_BACKTRACEDisables backtraces on non-panic errors even when
Other installation methods
The primary installation method, as described at https://rustup.rs, differs by platform:
- On Windows, download and run the rustup-init.exe built for
i686-pc-windows-gnutarget. In general, this is the build of
rustupone should install on Windows. Despite being built against the GNU toolchain, the Windows build of
rustupwill install Rust for the MSVC toolchain if it detects that MSVC is installed. If you prefer to install GNU toolchains or x86_64 toolchains by default this can be modified at install time, either interactively or with the
--default-hostflag, or after installation via
rustup set default-host.
- On Unix, run
curl https://sh.rustup.rs -sSf | shin your shell. This downloads and runs
rustup-init.sh, which in turn downloads and runs the correct version of the
rustup-initexecutable for your platform.
rustup-init accepts arguments, which can be passed through
the shell script. Some examples:
$ curl https://sh.rustup.rs -sSf | sh -s -- --help $ curl https://sh.rustup.rs -sSf | sh -s -- --no-modify-path $ curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain nightly $ curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain none $ curl https://sh.rustup.rs -sSf | sh -s -- --profile minimal --default-toolchain nightly
If you prefer you can directly download
rustup-init for the
platform of your choice:
MSVC builds of
rustup additionally require an installation of
Visual Studio 2019 or the Visual C++ Build Tools 2019. For
Visual Studio, make sure to check the "C++ tools" and "Windows
10 SDK" option. No additional software installation is necessary
for basic use of the GNU build.
You can fetch an older version from
To install from source just run
cargo run --release. Note that
rustup only builds on nightly Rust, and that after
rustup toolchains will supersede any pre-existing
toolchains by prepending
~/.cargo/bin to the
rustup is secure enough for the non-paranoid, but it still needs
rustup performs all downloads over HTTPS, but does not
yet validate signatures of downloads.
File modes on installation honor umask as of 1.18.4, use umask if very tight controls are desired.
Is this an official Rust project?
Yes. rustup is an official Rust project. It is the recommended way to install Rust at https://www.rust-lang.org.
How is this related to multirust?
Can rustup download the Rust source code?
The Rust source can be obtained by running
rustup component add rust-src.
It will be downloaded to the
directory of the current toolchain.
rustup fails with Windows error 32
rustup fails with Windows error 32, it may be due to antivirus
scanning in the background. Disable antivirus scanner and try again.
I get "error: could not remove 'rustup-bin' file: 'C:\Users\USER\.cargo\bin\rustup.exe'"
rustup fails to self-update in this way it's usually because RLS is
running (your editor is open and running RLS). The solution is to stop RLS (by
closing your editor) and try again.
Copyright Diggory Blake, the Mozilla Corporation, and rustup contributors.
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.