Downloading and Installing Rust
A step-by-step guide to installing Rust using rustup on Linux, macOS, and Windows, including verification, troubleshooting, and updates
Rust's primary installation method is rustup, a command-line tool that downloads and manages the Rust compiler, the standard library, and the cargo package manager. rustup also handles updates, cross-compilation targets, and switching between stable, beta, and nightly release channels. Using rustup ensures you always have a consistent, supported Rust environment on any platform.
Why rustup?:
You might see Rust available through your system's package manager (like apt, dnf, or Homebrew). Those versions work but are often outdated and cannot install multiple toolchains or targets the way rustup can. Unless you have a specific reason to use a system package, rustup is the recommended path.
Installing Rust with rustup
The installation process differs slightly depending on your operating system. Choose the tab that matches your machine and follow the steps in order. Each sequence assumes you are starting with a clean environment where Rust has not been installed before.
Step 1: Check for prerequisites
On Linux, macOS, and Windows Subsystem for Linux, you only need a standard terminal and the curl tool. Most systems already have it. Verify by running:
curl --version
If you see a version number, you're set. If not, install curl through your package manager (e.g., sudo apt install curl on Debian/Ubuntu).
Step 2: Run the rustup installer
Execute the official installation script. The command uses --proto '=https' and --tlsv1.2 to enforce a secure connection.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
When you run this, rustup downloads and starts an interactive setup. The default installation is almost always the right choice — it installs the stable toolchain to ~/.cargo/bin and adds the necessary directories to your PATH.
Review before piping:
Piping a remote script directly into sh is a security practice that some developers prefer to avoid. You can always download the script first with curl -O https://sh.rustup.rs, inspect it, then run sh rustup.sh. The script is open source and maintained by the Rust project.
Step 3: Follow the on-screen prompts
The installer will display something like:
Welcome to Rust!
This will download and install the official compiler for the Rust
programming language, and its package manager, Cargo.
...
Current installation options:
default host triple: x86_64-unknown-linux-gnu
default toolchain: stable (default)
profile: default
modify PATH variable: yes
1) Proceed with standard installation (default - just press enter)
2) Customize installation
3) Cancel installation
Press Enter to accept the default. rustup will fetch the latest stable compiler, the cargo build system, the standard library documentation, and the rustup binary itself.
Step 4: Configure your PATH environment variable
The installer tries to add ~/.cargo/bin to your PATH automatically by modifying your shell's startup file (.bashrc, .zshrc, .profile, etc.). To make the changes take effect in your current terminal, either:
- Close and reopen the terminal, or
- Source the modified file manually:
source "$HOME/.cargo/env"
The second approach is faster and works for the current session. The environment file updates PATH immediately without a full logout.
Step 5: Verify the installation
Check that the compiler is reachable and working:
rustc --version
You should see output like rustc 1.80.0 (73528c5d 2024-07-25). The exact version number will be newer if you are reading this later, but any version number means Rust is installed correctly.
Rust is ready:
If rustc --version prints a version, the compiler, cargo, and rustup are all installed and accessible. You can now compile Rust programs on this machine.
Troubleshooting Installation Issues
Most installation problems fall into a few common categories. If you hit a wall, check the situation that matches what you're seeing.
rustc is not recognized (command not found)
This almost always means the directory containing the Rust tools is not on your PATH, or your terminal hasn't reloaded the PATH changes yet.
Compiler not found after installation:
Symptom: After running the installer, you type rustc --version and get command not found (Unix) or 'rustc' is not recognized (Windows).
Likely cause: The PATH was not updated for your current terminal session.
Fix on Unix: Run source "$HOME/.cargo/env" or restart your terminal. Verify that ~/.cargo/bin appears in echo $PATH. If not, add export PATH="$HOME/.cargo/bin:$PATH" to your shell's startup file manually.
Fix on Windows: Open a new Command Prompt or PowerShell window. If the problem persists, ensure %USERPROFILE%\.cargo\bin is listed in your system environment variables (search "Edit environment variables" in the Start menu).
Linker errors on Windows (link.exe not found)
When compiling even a simple Rust program on Windows, you may encounter:
error: linker `link.exe` not found
This means the MSVC build tools are not installed or not in your PATH. Revisit Step 1 of the Windows installation and make sure the C++ build tools workload was selected during the Visual Studio Build Tools installation. After installing, restart your terminal and try again.
Permission denied when running the installer
On Unix systems, if you see Permission denied during the installation script, check that the curl pipeline has execution rights and that your home directory is writable. Do not run the installer with sudo — rustup is designed to install into your user directory. Using sudo will create files owned by root in your home directory, leading to permission headaches later.
If the error is about writing to /usr/local, that indicates the script is trying to install system-wide (which it shouldn't by default). Try reinstalling with the explicit --prefix option pointing to a location you own.
Network issues or proxy failures
The rustup installer downloads files from https://static.rust-lang.org. If you are behind a corporate firewall or using a proxy, set the https_proxy environment variable before running the installer:
export https_proxy=http://proxy.example.com:8080
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
The same environment variable is used by rustup itself for subsequent updates.
Updating Rust
Rust is released on a six-week stable cycle. Keeping your toolchain current is a single command:
rustup update
This fetches the latest versions of the stable toolchain, cargo, and the standard library. It also updates rustup itself. You can run it anytime; if nothing has changed, it simply confirms you are on the latest version.
To check what toolchains are currently installed and which is the default:
rustup show
The output lists the active toolchain and any additional toolchains you might have added (such as beta or nightly). If you ever need a specific version for compatibility testing, rustup can install it without affecting the default.
Uninstalling Rust
If you need to remove Rust completely from your machine, rustup can clean up everything it installed.
Step 1: Run the uninstall command
rustup self uninstall
This command removes the rustup binary, all installed toolchains, cargo, and the associated configuration files. It does not remove any Rust projects or source files you created — those remain in their directories.
Step 2: Clean up the cargo directory (optional)
The uninstall command leaves behind the ~/.cargo directory (or %USERPROFILE%\.cargo on Windows) if it contains files that were not managed by rustup, such as registry caches or your personal Cargo configuration. To fully wipe all Rust traces, delete that directory manually:
rm -rf ~/.cargo
On Windows, delete the %USERPROFILE%\.cargo folder from File Explorer.
Step 3: Remove PATH entries (optional)
The uninstaller attempts to remove the Rust directory from your PATH. To verify, open a fresh terminal and run rustc --version. If the command still works, the PATH entry remains. On Unix, check your shell's startup files (.bashrc, .zshrc, etc.) and remove the line that adds ~/.cargo/bin to PATH. On Windows, remove the entry from the system environment variables manually.
Rust is now on your machine, managed by rustup, and ready for use.