Support for rustup category home mode

[Cloud0310]

Related to #247.

Summary

Rustup historically stores configuration, state, data, and caches under a single RUSTUP_HOME (defaulting to $HOME/.rustup), while rustup and its proxies are installed under CARGO_HOME/bin.

This PR introduces an opt-in category-home layout guarded by RUSTUP_USE_CATEGORY_HOME, while preserving the legacy layout by default.

When category mode is enabled (RUSTUP_USE_CATEGORY_HOME=1 or any non-empty value other than "0"):

Category	Contents	Platform Default
Cache	downloads/, tmp/, update-hashes/	Unix: $XDG_CACHE_HOME/rustup or ~/.cache/rustup Windows: Local AppData rustup
Config	settings.toml	Unix: $XDG_CONFIG_HOME/rustup or ~/.config/rustup Windows: Roaming AppData rustup
Data	toolchains/, fallback/, generated shell env scripts	Unix: $XDG_DATA_HOME/rustup or ~/.local/share/rustup Windows: Roaming AppData rustup
State	state.toml, self-update/	Unix: $XDG_STATE_HOME/rustup or ~/.local/state/rustup Windows: Roaming AppData rustup
Bin	Rustup and proxies (rustc, cargo, etc.)	Unix: ~/.local/bin Windows: %USERPROFILE%/.local/bin (tentative)

Important

Why gated?
Gating both category-specific overrides and platform defaults avoids split-brain installations where external tools still look exclusively in RUSTUP_HOME for toolchains.

Enabling category mode selects the new locations; it does not migrate an existing installation.

---

Resolution Precedence

Note

Explicit RUSTUP_HOME and CARGO_HOME settings remain in the resolution order for backward compatibility. Category-specific overrides and platform defaults are only active when category mode is enabled.

Design Guidance

The legacy layout remains the default. Category mode splits Rustup's resources across independently resolved homes while preserving explicit legacy overrides.

This PR does not redefine RUSTUP_HOME as a common base directory for every category, and the binary directory does not fall back to RUSTUP_HOME/bin. Further changes to those semantics can be considered separately after the category layout is rolled out.

Categories (Cache / Config / Data / State)

In category mode:

1. RUSTUP_<CATEGORY>_HOME
2. Explicit RUSTUP_HOME
3. The platform category directory

When category mode is disabled, category-specific overrides are ignored and all four categories use the resolved legacy RUSTUP_HOME.

Note

On Unix, explicit absolute XDG_ variables take precedence over $HOME-derived paths. Empty or relative XDG values are ignored.
Windows does not consult XDG variables.

Bin Directory

In category mode:

1. RUSTUP_BIN_HOME
2. Explicit CARGO_HOME/bin
3. The platform default bin directory

When category mode is disabled, Rustup continues to use the resolved legacy CARGO_HOME/bin.

The current category-mode default is ~/.local/bin on Unix and %USERPROFILE%/.local/bin on Windows. The Windows default remains open for discussion.

---

Important Commits

feat(home): resolve opt-in category homes

Implements the directory resolution rules and opt-in rollout strategy across three layers:

1. process.rs selects the legacy or category layout through RUSTUP_USE_CATEGORY_HOME.
2. process/home.rs applies category-specific overrides, explicit legacy overrides, and platform defaults.
3. process/home/{unix,windows}.rs resolves XDG directories on Unix and Known Folders on Windows.

The gate controls both the new category-specific overrides and the platform defaults. When it is disabled, the existing RUSTUP_HOME and CARGO_HOME behavior remains unchanged.

fix(toolchain): preserve legacy home forwarding across home modes

Defines how Rustup's resolved directory choices are passed to toolchain child processes.

Toolchain commands receive the resolved config, data, cache, state, and bin homes through their corresponding environment variables. Legacy mode continues to forward RUSTUP_HOME, while category mode forwards the resolved category homes instead.

Rustup also sets RUSTUP_TOOLCHAIN and places the resolved proxy directory at the front of the child process's PATH, so later Cargo, rustc, and proxy invocations use the same toolchains and directory selection as the parent process.

CARGO_HOME remains separate from Rustup's category homes. Legacy mode preserves the existing resolution and forwarding behavior; category mode resolves and forwards it when the variable is explicitly present.

feat(shell): use env home for installation scripts and setup

Generated shell environment scripts use the data home in category mode and the Cargo home in legacy mode.

Script generation, shell profile entries, post-install instructions, and uninstall cleanup use the resolved env home. The scripts themselves add the independently resolved bin home to PATH; they no longer assume that the env scripts and Rustup binaries share a parent directory.

With the default Unix category layout, a POSIX shell sources ~/.local/share/rustup/env, which adds ~/.local/bin to PATH.

fix(windows): make uninstall GC independent of installation directories

Runs the Windows uninstall GC helper from an independent regular-file copy in the system temporary directory.

This avoids requiring write access to the parent of CARGO_HOME or another installation directory. Copying the executable contents instead of preserving a symbolic link also ensures that the delete-on-close handle targets the temporary GC copy rather than the installed rustup executable.

The GC helper attempts its own cleanup even if uninstalling the Rustup installation fails.

feat(uninstall): clean legacy and category installations

Legacy mode retains the existing Rustup and Cargo home cleanup behavior.

In category mode, uninstall removes the current toolchains, generated shell environment scripts, and rustup-managed binaries without treating the category homes or bin home as exclusively owned by Rustup.

Proxy removal uses same-file checks against the installed rustup executable. Unrelated files are preserved, a non-empty shared bin directory is left in place, and a separate legacy installation is not removed as part of category-mode uninstall.

---

Open Questions

1. Windows Bin Location:
   • Currently set to %USERPROFILE%/.local/bin.
   • Alternatives based on Windows Known Folders remain under discussion.
   • The final choice should account for platform conventions, shared-directory ownership, PATH precedence, and migration from %USERPROFILE%/.cargo/bin.

Following tasks

• Design and implement a CLI interface for migrating existing installations to category mode.
• Decide the rollout and migration-warning UX.
• Update the user guide for the new mode.

[Cloud0310]

About Windows' bin directory location problem, here's more context:

Directory	Pros	Cons	Precedent
%USERPROFILE%\.local\bin	Consistent across platforms; shared PATH entry	Not a Windows Known Folder; shared filenames complicate collision handling and cleanup	uv and uv tool install use this directory
%LOCALAPPDATA%\rustup\bin	Clear ownership; relatively short path	Separate PATH entry; application-defined layout	pnpm 11+ uses %LOCALAPPDATA%\pnpm\bin
%LOCALAPPDATA%\Programs\Rustup\bin	Standard per-user programs parent directory; clear ownership	Longer path; separate PATH entry	VS Code user setup installs under %LOCALAPPDATA%\Programs\Microsoft VS Code

@ChrisDenton @rami3l , Current PR's defaulting to use %USERPROFILE%\.local\bin, but I think we need to discuss upon this.

[ChrisDenton]

Hm, since I feel one of the points of this feature is to use more platform native paths, I don't think %USERPROFILE%\.local\bin is the best choice. That seems quite alien to Windows. I suppose a more Windows-like equivalent would be %LOCALAPPDATA%\Programs\bin but I don't think there's much (if any) precedent for that.

I think either of the other two options are justifiable. Putting it under "Programs" is the most technically correct I guess but if anything there's a weaker precedent for that, albeit applications that used to support XP wouldn't have used it because "Programs" wasn't a thing back then.

[djc]

What are we doing for macOS here? The XDG stuff definitely doesn't feel native for it.

[ChrisDenton]

There appears to be a fairly strong use of XDG for macOS cli utilities. I cannot find any officially documented conventions that aren't intended for app bundles but unofficially almost everything in the shell seems to treat it as a Unix (which it is).

[Cloud0310]

There appears to be a fairly strong use of XDG for macOS cli utilities. I cannot find any officially documented conventions that aren't intended for app bundles but unofficially almost everything in the shell seems to treat it as a Unix (which it is).

That's what @rami3l and I wants as well.
I personally agree with this idea to consider macOS as Unix, which also agrees with current repo's state: we only maintain two major platforms: Unix/Windows.
Currently introducing another macOS specific code would not fit in.

[rami3l]

In terms of precedence of different configuration options, as I have discussed with @Cloud0310, the only remaining concern is what to do when RUSTUP_USE_CATEGORY_HOME=1 meets explicit RUSTUP_HOME or CARGO_HOME overrides.

As per the previous summary in https://blog.rust-lang.org/inside-rust/2025/10/01/this-development-cycle-in-cargo-1.90/#all-hands-xdg-paths:

The most immediate problem is Rustup setting CARGO_HOME. To not break compatibility, Cargo should always respect it if CARGO_HOME is set.

This means CARGO_HOME must have higher precedence than RUSTUP_USE_CATEGORY_HOME=1. To ensure consistency across both rustup and cargo, I propose that we treat RUSTUP_HOME similarly, hence the following fallback order:

1. RUSTUP_XXX_HOME. Setting this means that the user has explicitly deviated from the old paths. RUSTUP_USE_CATEGORY_HOME=1 only.
2. The old override path, whether that is CARGO_HOME/bin or RUSTUP_HOME/xxx.
3. The platformdirs-derived path that is derived from XDG on Unix, or the registry on Windows. RUSTUP_USE_CATEGORY_HOME=1 only.
4. The old default path, whether that is ~/.cargo/bin or ~/.rustup/xxx.

[rami3l]

What are we doing for macOS here? The XDG stuff definitely doesn't feel native for it.

AFAIK the standard library currently uses the same logic for macOS and Linux, so I think that is a very good default to start with: https://doc.rust-lang.org/stable/std/os/unix/xdg/fn.cache_home_dir.html

Also, this is the convention followed by other existing tools such as neovim and uv.

I am aware of the frequently-quoted macOS documentation page which to some may suggest paths like ~/Library/ApplicationSupport/rustup/toolchains etc.

I would again point out (as @ChrisDenton has mentioned above) that these guidelines are specific to app bundles (that page is full of app bundle-specific paths, with Library being the only out-of-bundle directory), for which using this convention may facilitate migration to iOS apps, sandboxed bundles or iCloud-synced data. However, none of the above would be interesting to rustup usage on macOS (also note that uv has explicitly migrated from macOS bundle-specific paths to general XDG paths).

If the user really prefers to place stuff in ApplicationSupport, we have explicit overrides for that on both rustup and XDG levels. Oftentimes they would only need to set an $XDG_CONFIG_HOME override and that will work for all their CLI apps, not just rustup.

[Cloud0310]

In terms of precedence of different configuration options, as I have discussed with @Cloud0310, the only remaining concern is what to do when RUSTUP_USE_CATEGORY_HOME=1 meets explicit RUSTUP_HOME or CARGO_HOME overrides.

As per the previous summary in https://blog.rust-lang.org/inside-rust/2025/10/01/this-development-cycle-in-cargo-1.90/#all-hands-xdg-paths:

The most immediate problem is Rustup setting CARGO_HOME. To not break compatibility, Cargo should always respect it if CARGO_HOME is set.

This means CARGO_HOME must have higher precedence than RUSTUP_USE_CATEGORY_HOME=1. To ensure consistency across both rustup and cargo, I propose that we treat RUSTUP_HOME similarly, hence the following fallback order:

1. RUSTUP_XXX_HOME. Setting this means that the user has explicitly deviated from the old paths. RUSTUP_USE_CATEGORY_HOME=1 only.
2. The old override path, whether that is CARGO_HOME/bin or RUSTUP_HOME/xxx.
3. The platformdirs-derived path that is derived from XDG on Unix, or the registry on Windows. RUSTUP_USE_CATEGORY_HOME=1 only.
4. The old default path, whether that is ~/.cargo/bin or ~/.rustup/xxx.

This also has an effect on the env var recursive forwarding system, I guess once we're in new mode, I need to stop forwarding cargo_home and rustup_home in case of causing underlaying program having confusing about if this var is from manually setting or from rustup resolution.

[rami3l]

This also has an effect on the env var recursive forwarding system, I guess once we're in new mode, I need to stop forwarding cargo_home and rustup_home in case of causing underlaying program having confusing about if this var is from manually setting or from rustup resolution.

@Cloud0310 Exactly, and I'd like to see more regression tests on this point to make sure that we have done the right thing.

[djc]

For macOS, I'm particularly concerned about the cache directories. If we don't put them in the location that the OS understands, we basically don't get to benefit from the OS managing caches, which seems bad.

For binaries, won't it cause issues if we share a bin dir with other tooling as opposed to the rustup/Cargo-specific bin we have today?

[rami3l]

For binaries, won't it cause issues if we share a bin dir with other tooling as opposed to the rustup/Cargo-specific bin we have today?

@djc What potential issues do you have in mind to be precise?

• In terms of directory nuking the semantics has already been changed in Stop nuking $CARGO_HOME (~/.cargo) on rustup self uninstall #285, as many would prefer to keep the cargo-installed binaries after rustup self uninstall in the first place.
• In terms of defaults I think it'd be okay to default to a common directory as everyone else (such as UV and cabal) but we keep the possibility of having a specific one.

I'm particularly concerned about the cache directories. If we don't put them in the location that the OS understands, we basically don't get to benefit from the OS managing caches, which seems bad.

I am aware of special macOS mechanisms that may force the shrinking of ~/Library/Caches from time to time, but the point here, at least for me, is that we are actively cleaning up RUSTUP_CACHE_HOME so the size of that dir should be below 1MiB almost all the time (after a transaction has successfully finished), so this is not a concern here. However I'm curious what the std/uv people think about this.

[Cloud0310]

About Windows' bin directory location problem, here's more context:

Directory Pros Cons Precedent
%USERPROFILE%\.local\bin Consistent across platforms; shared PATH entry Not a Windows Known Folder; shared filenames complicate collision handling and cleanup uv and uv tool install use this directory
%LOCALAPPDATA%\rustup\bin Clear ownership; relatively short path Separate PATH entry; application-defined layout pnpm 11+ uses %LOCALAPPDATA%\pnpm\bin
%LOCALAPPDATA%\Programs\Rustup\bin Standard per-user programs parent directory; clear ownership Longer path; separate PATH entry VS Code user setup installs under %LOCALAPPDATA%\Programs\Microsoft VS Code
@ChrisDenton @rami3l , Current PR's defaulting to use %USERPROFILE%\.local\bin, but I think we need to discuss upon this.

@epage what's cargo's decision here? Maybe we want to sync this "favor" choice with cargo team.

[rami3l]

@epage Note that we are not pressuring cargo to do the final decision because in the opt-in period we can still change the default value, but it'd be interesting to see if we can land on something in common first.

@Cloud0310 For Windows’ bin dir my personal preference would be the option 2 (PNPM) above.

[djc]

I think the commit history here could stand to be improved. Would suggest:

• Move all commits that are not directly related to this feature into another PR (chore(process.rs): re-organize imports, potentially some of refactor(installer): generalize path formatting helpers)
• Then have one commit per each of the 5 categories here, from least to most intrusive

[Cloud0310]

@Cloud0310 For Windows’ bin dir my personal preference would be the option 2 (PNPM) above.
Why option 2 here? I want your reason.

Untill we finally out of opt-in period and settle on this choice, I would just keep using %USERPROFILE%\.local\bin with a TODO comment for this in current PR.

[rami3l]

I have carefully assessed your patch and especially all the behaviors related to the case where RUSTUP_USE_CATEGORY_HOME=1 is not set, and I think the chances of breakage are minimal.

As such, I think it is time to approve it now. Any further changes to the feature could be addressed in follow-up PRs.

Before actually merging it, I'd like you to make sure that the PR description is up to date and matches your current implementation (some details such as the bin_path on Windows have been changed during your iterations, for example). It will help anyone who comes after to have the right full picture.

Many thanks again for participating GSoC 2026 to help us out with rustup and all the iterations you have done!

View changes since this review

[Cloud0310]

I have carefully assessed your patch and especially all the behaviors related to the case where RUSTUP_USE_CATEGORY_HOME=1 is not set, and I think the chances of breakage are minimal.

As such, I think it is time to approve it now. Any further changes to the feature could be addressed in follow-up PRs.

Before actually merging it, I'd like you to make sure that the PR description is up to date and matches your current implementation (some details such as the bin_path on Windows have been changed during your iterations, for example). It will help anyone who comes after to have the right full picture.

Many thanks again for participating GSoC 2026 to help us out with rustup and all the iterations you have done!

View changes since this review

I still have some little nits for refine, and the PR description update is on it's way here.

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[rustbot]

☔ The latest upstream changes (possibly #5142) made this pull request unmergeable. Please resolve the merge conflicts.