Install Rust on Linux, macOS and Windows

Which option to pick

The Rust project recommends rustup on every platform, and in practice everyone uses it: it installs the compiler rustc, the build tool and package manager cargo, documentation and other components into your home directory, keeps them updated with one command, and can hold several toolchains (stable, beta, nightly) side by side. Distribution packages such as apt install rustc exist but are frozen at release time, and Rust projects move quickly. The only extra requirement is a system linker: a C compiler toolchain on Linux and macOS, or the Microsoft C++ build tools on Windows.

Step: Linux

Install a C toolchain first, then rustup:

sudo apt install build-essential
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"

On Fedora the first line is sudo dnf install gcc, on Arch sudo pacman -S base-devel. The rustup script asks a question; the default option 1 installs the stable toolchain and adds ~/.cargo/bin to your PATH through your shell startup files. The final line applies that to the current shell.

Step: macOS

xcode-select --install
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"

The command line tools provide the linker. brew install rustup is an alternative way to get rustup itself; after it, run rustup-init once. Avoid brew install rust, which installs a fixed toolchain without rustup.

Step: Windows

winget install Rustlang.Rustup

Or download and run rustup-init.exe from rustup.rs. The installer checks for the Visual Studio C++ build tools and offers to install them if they are missing; accept, because the default Windows toolchain (x86_64-pc-windows-msvc) needs Microsoft’s linker. This download is large. Afterwards, open a new terminal so cargo is on PATH.

Check it works

rustc --version
cargo --version
rustup --version

Then create, build and run a project to confirm the linker works as well as the compiler:

cargo new hello-rust
cd hello-rust
cargo run

The output ends with Hello, world!. Later, update everything with rustup update, and open the offline documentation with rustup doc.

Common problems

• error: linker `cc` not found on Linux: install the C toolchain (build-essential or gcc) and build again.
• cargo: command not found in a new terminal: the startup file was not updated or is not the one your shell reads. Add . "$HOME/.cargo/env" to ~/.bashrc or ~/.zshrc.
• Windows: error: linker `link.exe` not found: the Visual Studio C++ build tools are missing. Re-run the Visual Studio Installer and add the Desktop development with C++ workload, or switch to the GNU toolchain with rustup default stable-x86_64-pc-windows-gnu.
• Builds fail after a long time with a crate needing a newer compiler: run rustup update; projects can also pin their version in a rust-toolchain.toml file, which rustup honours automatically.

Official documentation

• Install Rust
• The rustup book
• The Rust Programming Language: Installation