rustup-toolchain

Install or update a given toolchain

$ rustup toolchain install [toolchain]

$ rustup toolchain uninstall [toolchain]

$ rustup toolchain list

$ rustup toolchain link [custom_toolchain_name] [path/to/directory]

rustup toolchain SUBCOMMAND [OPTIONS]

list
    Lists all installed Rust toolchains on your system, indicating the active and default ones.

install toolchain
    Installs a specified Rust toolchain (e.g., stable, beta, nightly, 1.70.0). This command downloads and sets up the compiler, standard library, and common components for the chosen toolchain.

 --component component
    Used with install to add an additional component (e.g., rust-src, rust-docs, clippy) to the toolchain during installation or later.

 --target target-triple
    Used with install to install a toolchain for a specific cross-compilation target (e.g., x86_64-unknown-linux-gnu, armv7-unknown-linux-gnueabihf), enabling cross-platform development.

uninstall toolchain
    Removes a previously installed Rust toolchain from your system, freeing up disk space.

link name path
    Links a local directory as a custom toolchain under a given name. This is useful for testing custom builds of rustc or integrating toolchains not installed by rustup itself.

default toolchain
    Sets the specified toolchain as the default for your system. This toolchain will be used when you invoke rustc or cargo without explicitly selecting a toolchain.

show
    Displays information about the currently active toolchain in the current directory or globally, along with any overrides.

rustup toolchain is the primary subcommand within rustup used for managing different Rust toolchains. Rust toolchains are specific versions of the Rust compiler (rustc), standard library, and associated tools (like cargo, rustfmt, clippy). Users often need multiple toolchains for various reasons: stable for general development, beta for trying upcoming features, nightly for cutting-edge experimental features, or specific older versions for compatibility.

This command allows users to install new toolchains, uninstall existing ones, list all installed toolchains, set a default toolchain for the system, and link custom-built toolchains or those installed from other sources. It provides a flexible way to switch between different Rust development environments seamlessly, which is crucial for modern Rust development practices, enabling testing against various compiler versions or supporting projects requiring specific toolchains.

Internet access is required for install and update operations, as toolchains are downloaded from the internet.
Linking custom toolchains with link requires careful path management to ensure the linked binaries are correctly found and used.
Installing multiple toolchains or various components can consume significant disk space over time.

Beyond setting a global default, rustup allows setting directory-specific toolchain overrides. By navigating to a directory and running rustup override set <toolchain>, you can ensure that a specific toolchain is used automatically whenever you are in that directory or any of its subdirectories. This is particularly useful for projects that require a specific Rust version for compilation.

Rust toolchains are modular. Commands like rustup component add <component> (which targets the currently active toolchain) allow adding specific functionalities like rust-analyzer (LSP server), clippy (linter), or rustfmt (formatter) to an installed toolchain, ensuring a tailored development environment without reinstalling the entire toolchain.

Before the advent of rustup, managing different Rust compiler versions was a largely manual process, often involving uninstalling and reinstalling Rust, or using custom scripts. This made experimenting with new features or maintaining projects reliant on older Rust versions cumbersome.

rustup was developed to streamline this process, becoming the official Rust toolchain installer and manager. The toolchain subcommand is central to its functionality, providing a robust, consistent interface for developers to switch between stable, beta, and nightly releases, as well as specific historical versions. Its design emphasizes flexibility and ease of use, making it a cornerstone of the modern Rust development workflow.

rustup(1), cargo(1), rustc(1), rustup-default(1), rustup-update(1)