Rustup for managing Rust versions

(this tool has its own versioning scheme and works with all Rust versions)

The Rustup tool has become the recommended way toinstall Rust, and is advertised on our website. Its powers go further thanthat though, allowing you to manage various versions, components, andplatforms.

For installing Rust

To install Rust through Rustup, you can go tohttps://www.rust-lang.org/install.html, which will let you know how to doso on your platform. This will install both rustup itself and the stableversion of rustc and cargo.

To install a specific Rust version, you can use rustup install:

$ rustup install 1.30.0

This works for a specific nightly, as well:

$ rustup install nightly-2018-08-01

As well as any of our release channels:

$ rustup install stable
$ rustup install beta
$ rustup install nightly

For updating your installation

To update all of the various channels you may have installed:

$ rustup update

This will look at everything you've installed, and if there are new releases,will update anything that has one.

Managing versions

To set the default toolchain to something other than stable:

$ rustup default nightly

To use a toolchain other than the default, use rustup run:

$ rustup run nightly cargo build

There's also an alias for this that's a little shorter:

$ cargo +nightly build

If you'd like to have a different default per-directory, that's easy too!If you run this inside of a project:

$ rustup override set nightly

Or, if you'd like to target a different version of Rust:

$ rustup override set 1.30.0

Then when you're in that directory, any invocations of rustc or cargowill use that toolchain. To share this with others, you can create arust-toolchain file with the contents of a toolchain, and check it intosource control. Now, when someone clones your project, they'll get theright version without needing to override set themselves.

Installing other targets

Rust supports cross-compiling to other targets, and Rustup can help youmanage them. For example, to use MUSL:

$ rustup target add x86_64-unknown-linux-musl

And then you can

$ cargo build --target=x86_64-unknown-linux-musl

To see the full list of targets you can install:

$ rustup target list

Installing components

Components are used to install certain kinds of tools. While cargo-installhas you covered for most tools, some tools need deep integration into thecompiler. Rustup knows exactly what version of the compiler you're using, andso it's got just the information that these tools need.

Components are per-toolchain, so if you want them to be available to morethan one toolchain, you'll need to install them multiple times. In thefollowing examples, add a —toolchain flag, set to the toolchain youwant to install for, nightly for example. Without this flag, it willinstall the component for the default toolchain.

To see the full list of components you can install:

$ rustup component list

Next, let's talk about some popular components and when you might want toinstall them.

rust-docs, for local documentation

This first component is installed by default when you install a toolchain. Itcontains a copy of Rust's documentation, so that you can read it offline.

This component cannot be removed for now; if that's of interest, pleasecomment on thisissue.

rust-src for a copy of Rust's source code

The rust-src component can give you a local copy of Rust's source code. Whymight you need this? Well, autocompletion tools like Racer use thisinformation to know more about the functions you're trying to call.

$ rustup component add rust-src

rustfmt for automatic code formatting

If you'd like to have your code automatically formatted, you caninstall this component:

$ rustup component add rustfmt

This will install two tools, rustfmt and cargo-fmt, that will reformat yourcode for you! For example:

$ cargo fmt

will reformat your entire Cargo project.

rls for IDE integration

Many IDE features are built off of the langserverprotocol. To gain support for Rust with these IDEs,you'll need to install the Rust language sever, aka the "RLS":

$ rustup component add rls

For more information about integrating this into your IDE, see the RLSdocumentation.

clippy for more lints

For even more lints to help you write Rust code, you can install clippy:

$ rustup component add clippy

This will install cargo-clippy for you:

$ cargo clippy

For more, check out clippy'sdocumentation.

The "preview" components

There are several components in a "preview" stage. These components currentlyhave -preview in their name, and this indicates that they're not quite 100%ready for general consumption yet. Please try them out and give us feedback,but know that they do not follow Rust's stability guarantees, and are stillactively changing, possibly in backwards-incompatible ways.

llvm-tools-preview for using extra LLVM tools

If you'd like to use the lld linker, or other tools like llvm-objdump orllvm-objcopy, you can install this component:

$ rustup component add llvm-tools-preview

This is the newest component, and so doesn't have good documentation at themoment.