Tracking: Default implicit install restrictions

Summary

This issue is intended to gather community feedback on the future direction of rustup's automatic install behaviour. It suggests some changes to the way rustup does implicit installs by default but these proposals are subject to change based on feedback.

Background

Currently rustup will implicitly install the active toolchain if it isn't installed already. This happens when you run almost any rustup command or using a tool managed by rustup, such as cargo or rustc (these are called "shims").

The active toolchain is usually controlled by the user. but, as detailed on the Overrides page of the book, a project can contain a rustup-toolchain.toml file to override the user's preference.

In this example of an override, we set the toolchain to use nightly-2025-03-20 for their current host:

[toolchain]
channel = "nightly-2025-03-20"

A toolchain override can also be a path to a custom toolchain:

[toolchain]
# `path` is relative to the project directory
path = "./my-toolchain"

Users can override this override using the + syntax (e.g. cargo +stable build) or by using rustup override.

Different projects use a rustup-toolchain.toml for different purposes. For example:

• The project relies on unstable nightly features which are only guaranteed to work with a specific version.
• It contains the MSRV. The project will compile with newer versions but the toolchain file records the lowest version that works.
• It's for CI. The project wants to lock the rustc version used in CI.
• A custom toolchain is required. Either to support platforms that don't have official build or for custom builds of official platforms.

How rustup is used

rustup is used in a variety of different contexts which may have different requirements. For example:

• Interactively on the command line.
• In non-interactive scripts.
• In CI.
• In the background by IDEs, e.g. for Language Server Protocols (LSPs) such as rust-analyzer

Additionally rustup can be used when either the user or systems has resource constraints:

• Internet access is not available, unreliable, slow or otherwise undesirable
• Drive space is limited or restricted in some way

Problems

Silent background installs

As mentioned above, IDEs use rustup in the background when they call cargo or rustc. This means that toolchains can be installed completely silently. This also means that downloads are more likely to occur concurrently with other uses of rustup. This can currently cause errors and other problems due to lack of filesystem locking but even when that is fixed it will cause the user to be blocked until the IDE finishes downloading a toolchain.

Trust

The current default implicitly trusts the rustup-toolchain.toml file. Since it's common to download projects from the internet, this is not a great default. Making this worse is the path override, which can mean implicitly trusting binaries downloaded from the internet without user intervention.

Control

Users should ultimately be in control of which toolchains are installed and used.

While it is possible to override rustup-toolchain.toml using rustup override, this isn't easy to discover naturally and in any case requires a lot more vigilance. The + syntax can also be used as an override but this requires remembering to use it for every single command that goes through rustup.

Next steps

These steps are intended to have minimal impact on current uses of rustup but take care of some edge cases. They do not address all the above issues.

• If the project's rustup-toolchain.toml uses a path based toolchain then this will always require an explicit install if it's not installed already.
• Only when running tools, such as cargo, should implicit installs happen. Explicit installs can be done via the rustup install command.
• No other rustup commands should cause an implicit install (e.g. rustup --version).

Future possibilities

Trusting rustup-toolchain.toml

It would be good for the user to be given a choice on how they want to handle a rustup-toolchain.toml file in a project. E.g.:

• Install once. The user will be prompted again the next time the file requires a new toolchain to be installed.
• Always trust the rustup-toolchain.toml file. This will mean changes in the file can cause implicit installs of new toolchains
• Ignore. The override will not take effect and the user's default toolchain will be used instead.

This would allow the user to have control over what gets installed on their system and to be able to easily user their preferred toolchain. The difficulty will be in providing a migration path, especially for CI.

Using --version on shims

Using --version on shims (such as cargo --version) should not trigger a download and install. People who use this intentionally to install toolchains should be migrated to rustup install, first with warnings and later becoming a hard error.

Unanswered questions

Interaction with the "safe file discovery" RFC

The Cargo and Rustup safe file discovery RFC proposes limiting the directories visited by cargo and rustup to just those owned by the user to protect against other users on the same system being able to tamper with the current users' builds. It suggests the RUSTUP_SAFE_DIRECTORIES and CARGO_SAFE_DIRECTORIES environment variables to opt-out of this. Should rustup reuse these for other meanings of "safe" or would conflating these concepts be confusing?

Prior art

direnv is a tool that allows environment variables to be configured using a file in the current directory. Users must use direnv allow . to allow this and do so again for changes.

Start with the issue's descriptions of rustup commands, tool-managed shims such as cargo and rustc, and rustup-toolchain.toml overrides. The issue does not name implementation files or tests; a contributor would first need to resolve the proposed behavior and locate the relevant command and toolchain-selection entry points before defining completion criteria.