rustup-override

List directiory toolchain overrides

$ rustup override list

$ rustup override set [toolchain]

$ rustup override unset

$ rustup override unset --nonexistent

rustup override set <toolchain>
rustup override unset [<path>]
rustup override list

set
    Sets the active toolchain for the current directory or specified path. <toolchain> can be a channel name (e.g., 'stable', 'beta', 'nightly'), a specific version (e.g., '1.60.0'), or a custom toolchain.

unset []
    Removes the toolchain override for the current directory or a specified path. If <path> is not provided, the override for the current directory is removed.

list
    Lists all active toolchain overrides, showing the directory and the associated toolchain.

The rustup-override command is a subcommand of rustup, the official Rust toolchain installer and manager. It is used to manage per-directory toolchain overrides, allowing developers to specify a particular Rust toolchain (e.g., stable, beta, nightly, or a specific version like 1.60.0) that should be used when working within a specific directory and its subdirectories. This is incredibly useful for projects that require different Rust versions or build configurations, preventing conflicts and ensuring consistency. When an override is set, rustup creates a .rustup-toolchain file in the specified directory, containing the name of the overridden toolchain. When rustup is invoked (e.g., through rustc, cargo) within that directory, it reads this file and uses the specified toolchain instead of the globally active one or the one set via the RUSTUP_TOOLCHAIN environment variable. This enables seamless switching between project-specific Rust environments without manual configuration changes.

rustup toolchain overrides are set per directory and affect all subdirectories within that hierarchy. The override is established by creating a .rustup-toolchain file in the specified directory. This local override takes precedence over the globally active toolchain and any toolchain specified via the RUSTUP_TOOLCHAIN environment variable. Be aware that deleting this file or moving the directory will naturally remove or bypass the override.

When rustup override set is executed, a hidden file named .rustup-toolchain is created in the current directory (or the specified path). This file simply contains the name of the toolchain to be used (e.g., 'nightly' or 'stable-x86_64-unknown-linux-gnu'). When cargo or rustc are invoked within this directory or any of its subdirectories, rustup automatically detects and uses the toolchain specified in this file.

Rustup resolves which toolchain to use based on the following hierarchy, from highest to lowest precedence:

1. Directory Overrides: The toolchain specified by .rustup-toolchain in the current directory or an ancestor.
2. Environment Variable: The toolchain specified by the RUSTUP_TOOLCHAIN environment variable.
3. Default Toolchain: The globally configured default toolchain (set via rustup default).

The rustup-override command is an integral part of the rustup toolchain manager, which was developed to address the growing complexity of managing Rust toolchains across various platforms and release channels (stable, beta, nightly). As Rust's ecosystem matured and projects began to rely on specific compiler versions or features, the need for per-project toolchain isolation became evident. rustup-override was introduced to provide a robust and easy-to-use mechanism for developers to pin specific toolchains to individual project directories, significantly enhancing workflow flexibility and reproducibility for Rust developers.

rustup(1), rustup-toolchain(1), cargo(1), rustc(1)