Support for rustup category home mode by Cloud0310 · Pull Request #5056 · rust-lang/rustup

Cloud0310 · 2026-09-05T16:14:30Z

Related to #247.

Summary

Rustup historically stores configuration, state, data, and caches under a single RUSTUP_HOME (defaulting to $HOME/.rustup).
This prevents rustup from adhering to platform-standard directories (XDG on Unix, Known Folders on Windows).

This PR introduces an opt-in category-home layout guarded by RUSTUP_USE_CATEGORY_HOME, while preserving the legacy single-directory 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/`	`$XDG_CACHE_HOME/rustup` or `~/.cache/rustup`
Config	`settings.toml`	`$XDG_CONFIG_HOME/rustup` or `~/.config/rustup`
Data	`toolchains/`, `fallback/`	`$XDG_DATA_HOME/rustup` or `~/.local/share/rustup`
State	`state.toml`	`$XDG_STATE_HOME/rustup` or `~/.local/state/rustup`
Bin	Proxies (`rustc`, `cargo`, etc.)	Unix: `~/.local/bin` Windows: `%USERPROFILE%/.local/bin` (tentative)

Important

Why gated?
Gating both category overrides and platform defaults avoids split-brain installations where external tools (e.g. older rust-analyzer) still look exclusively in RUSTUP_HOME for toolchains.

Resolution Precedence

Note

This order still needs discussion, upon whether we should consider RUSTUP_HOME and CARGO_HOME. See open questions.

Design Guidance

We consider this as a breaking change, and RUSTUP_HOME as a purely legacy env
var, so in new mode, we don't use it anymore, so, on category mode available,
the fallback paths are ignored.

Categories (Cache / Config / Data / State)

RUSTUP_<CATEGORY>_HOME (if category mode is enabled)
RUSTUP_HOME (legacy shared override)
Platform category default (if category mode is enabled)
$HOME/.rustup (legacy fallback)

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

RUSTUP_BIN_HOME (if category mode is enabled)
Platform default bin directory (if category mode is enabled: ~/.local/bin)
$CARGO_HOME/bin
$HOME/.cargo/bin

Important Commits

feat(home): resolve category homes

Implements the core path resolution logic structured for future home crate compatibility across three layers:

Underlying platform resolution: Handles Unix XDG environment variables and Windows native directories.
home crate facade (mod home): Re-exports standard home APIs, implements RUSTUP_<CATEGORY>_HOME resolution and RUSTUP_HOME fallback without rollout logic.
Rollout strategy: Implements the gating logic driven by RUSTUP_USE_CATEGORY_HOME.

feat(uninstall): remove legacy and category rustup homes

Removes rustup home directories (config, cache, data, state) for both legacy and category layouts. (Excludes bin directory).

feat(uninstall): clean legacy and category cargo bin homes

Cleans up rustup-managed proxy binaries and symlinks across both legacy and category bin directories, leaving unrelated user binaries untouched.

feat(installer): migrate bin and env paths to split homes

Completes the installer-side migration from Cargo-owned paths to Rustup's resolved homes. In category mode, rustup binaries, proxy links, self-update artifacts, executable checks, and child-process PATH setup now use rustup_bin_home, while generated shell environment scripts use the config home through rustup_env_home. Legacy mode preserves the existing $CARGO_HOME layout.

The commit also updates shell profile integration, Windows PATH handling, installer messages, and end-to-end coverage for the split layout.

Open Questions

Windows Bin Location:
- Currently set to %USERPROFILE%/.local/bin. Needs community consensus on whether this is the appropriate platform default for Windows.
- Requires validating PATH precedence and migration UX from %USERPROFILE%\.cargo\bin.
Env Script Localtion
- source env script should be in data home, config home or somewhere else?

Following tasks

Create a cli interface for migration, rustup migration category-mode, for
creating symlinks in legacy dir, pointing to coorresponding category dirs.
Add warning message for asking user for migrating to new category mode.
Update user-guide for new mode

Cloud0310 · 2026-09-05T16:34:08Z

Fixed a minor CI/CD problem on Windows.

Cloud0310 · 2026-09-06T06:48:08Z

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 · 2026-09-06T11:46:09Z

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 · 2026-09-06T12:00:33Z

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

ChrisDenton · 2026-09-06T12:17:30Z

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 · 2026-09-06T18:51:40Z

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 · 2026-09-06T19:48:38Z

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:

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

rami3l · 2026-09-06T20:08:29Z

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 · 2026-09-07T03:27:02Z

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:

RUSTUP_XXX_HOME. Setting this means that the user has explicitly deviated from the old paths. RUSTUP_USE_CATEGORY_HOME=1 only.

The old override path, whether that is CARGO_HOME/bin or RUSTUP_HOME/xxx.

The platformdirs-derived path that is derived from XDG on Unix, or the registry on Windows. RUSTUP_USE_CATEGORY_HOME=1 only.

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 · 2026-09-07T07:42:49Z

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 · 2026-09-07T09:37:24Z

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 · 2026-09-07T09:57:38Z

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 · 2026-09-07T11:45:22Z

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 · 2026-09-07T12:44:30Z

@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 · 2026-09-07T12:57:27Z

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 · 2026-09-07T15:51:17Z

@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.

Cloud0310 · 2026-09-12T04:35:03Z

Self reviewed and checked again, also changed the resolution order as comment. And as for the forwarding system, I added extra conditions for making sure backward compatibility.
And as for split PRs, I guess maybe today or tomorrow it would be done.

rami3l · 2026-09-12T08:55:27Z

Guess the last question we can solve now would be: should we don't use home compatible API style for this PR

@Cloud0310 Make sure you do a proper backup of the current state of the work, but at this point given that the home crate APIs are not expected to receive major upgrades, I think it'd be safe enough to simplify the code and fold all home APIs that you have added in this repo into rustup's own module hierarchy.

It should be noted however, that this comment is purely about new APIs that in the original plan would be upstreamed to home. We don't want to eliminate all uses of the home crate just yet.

rami3l · 2026-09-14T12:48:07Z

+    #[cfg(any(unix, test))]
+    pub(crate) fn rustup_env_home(&self) -> io::Result<PathBuf> {
+        if self.use_category_home() {
+            home::category_home(home::HomeCategory::Config, self)


Could we place this elsewhere? Something like $<category>_home/env/, not sure if <category> should be data or config... Personally I'd prefer data.

Maybe we can look for prior art in this field, if any?

View changes since the review

Searched for prior arts, the most relavent case to this is GHCup, they are using $XDG_DATA_HOME/ghcup/env, defaulting to ~/.local/share/ghcup/env
And for uv, they're using .local/bin/env for this purpose, which is causing colllision with slurm as reported.

Cloud0310 · 2026-09-14T13:36:30Z

Updated PR description, two open question is solved, and we have a new problem:
Current installation of rustup generates a script for user to source for activate rustup environment. But in new mode, we should store it on config or data dir or somewhere else?

Personally, I would love to remove this later, as we're defaultly modifying profiles and PATH registries. Especially after the category mode is fully shiped and loaded as default, the dir for Unix would be ~/.local/bin, which should be considered as already in PATH. And if the user wants to override, I guess it's their responsibility for adding their override value into PATH. BTW, this should be in a future thing, not so related to current PR.

Generate shell source commands and environment scripts with absolute paths. Keep historical command formatting independent of new output. Recognize current and historical commands during installation and uninstallation, preserving existing setup and removing matching lines.

Use the resolved bin home for installation, proxies, self-update, and child process PATH entries. Write and source environment scripts from the resolved env home. Verify absolute shell paths with split homes located beneath HOME.

Remove the legacy rustup home dependency from Cfg and use the resolved category homes instead. Preserve resolved RUSTUP_HOME and CARGO_HOME forwarding in legacy mode. In category mode, leave RUSTUP_HOME inherited and only resolve and forward an explicitly non-empty CARGO_HOME.

…ectory

Remove rustup-managed binaries from both bin directories, preserving unrelated tools and removing directories only when empty. Clean Unix shell entries before deleting their home directories. On Windows, remove PATH entries for deleted bin directories unless --no-modify-path is set.

rami3l self-assigned this Sep 5, 2026

Cloud0310 force-pushed the xdg-final branch from e6a83f3 to ee81ba4 Compare September 5, 2026 16:33

rami3l self-requested a review September 5, 2026 17:28

rami3l linked an issue Sep 5, 2026 that may be closed by this pull request

Tracking: Support for platformdirs (platform-specific system directories) such as XDG Paths #247

Open

rami3l removed a link to an issue Sep 5, 2026

Tracking: Support for platformdirs (platform-specific system directories) such as XDG Paths #247

Open

Cloud0310 force-pushed the xdg-final branch from ee81ba4 to 30d9e6b Compare September 6, 2026 06:06

rami3l mentioned this pull request Sep 8, 2026

refactor(test/mock-bin): extract generic environment variable echo option #5064

Merged

This comment has been minimized.

Sign in to view

Cloud0310 force-pushed the xdg-final branch 4 times, most recently from 445ebaf to 5108cf3 Compare September 11, 2026 16:07

Cloud0310 mentioned this pull request Sep 11, 2026

Fix Windows CI's Powershell not propagate error by default #5070

Merged

Cloud0310 force-pushed the xdg-final branch from 5108cf3 to 469f34e Compare September 12, 2026 07:56

Cloud0310 force-pushed the xdg-final branch from 469f34e to 04ffda3 Compare September 13, 2026 09:38

Cloud0310 added 2 commits September 14, 2026 17:18

feat(home): resolve category homes

b59f6a4

refactor(self-update): resolve rustup home through Process

1a7ab69

Cloud0310 force-pushed the xdg-final branch from 04ffda3 to cf31a84 Compare September 14, 2026 09:18

rami3l reviewed Sep 14, 2026

View reviewed changes

Cloud0310 force-pushed the xdg-final branch from cf31a84 to f360f28 Compare September 14, 2026 14:22

Cloud0310 added 20 commits September 15, 2026 02:24

feat(config): expose rustup cache home through Cfg

3fa7b40

feat(update-hash): store update hashes in the cache home

10c8e12

feat(download): use the cache home for temporary files

8c950f6

feat(download): use the cache home for downloads

07ef298

feat(config): expose rustup config home through Cfg

8db86b5

feat(config): read and write settings in the config home

b61a5f8

feat(config): expose rustup data home through Cfg

b70af7d

feat(toolchain): use the data home for toolchains

b682635

feat(toolchain): migrate fallback directory to data home

14f625d

feat(config): expose rustup state home through Cfg

6132109

feat(state): read and write state in the state home

75c3c27

feat(installer): display split rustup home directories

1f13aa6

feat(cli): expose resolved category homes in rustup show

63b9b22

feat(uninstall): remove legacy and category rustup homes

661f894

fix(windows-gc): copy the running executable into the system temp dir…

ba00de8

…ectory

fix(uninstall): reuse resolved cargo home during cleanup

fb1ca69

Cloud0310 force-pushed the xdg-final branch from f360f28 to 7a98d0f Compare September 14, 2026 18:31

Uh oh!

Uh oh!

Conversation

Cloud0310 commented Sep 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Resolution Precedence

Design Guidance

Categories (Cache / Config / Data / State)

Bin Directory

Important Commits

feat(home): resolve category homes

feat(uninstall): remove legacy and category rustup homes

feat(uninstall): clean legacy and category cargo bin homes

feat(installer): migrate bin and env paths to split homes

Open Questions

Following tasks

Uh oh!

Cloud0310 commented Sep 5, 2026

Uh oh!

Cloud0310 commented Sep 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ChrisDenton commented Sep 6, 2026

Uh oh!

djc commented Sep 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ChrisDenton commented Sep 6, 2026

Uh oh!

Cloud0310 commented Sep 6, 2026

Uh oh!

rami3l commented Sep 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rami3l commented Sep 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Cloud0310 commented Sep 7, 2026

Uh oh!

rami3l commented Sep 7, 2026

Uh oh!

djc commented Sep 7, 2026

Uh oh!

rami3l commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Cloud0310 commented Sep 7, 2026

Uh oh!

rami3l commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

djc commented Sep 7, 2026

Uh oh!

Cloud0310 commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

Cloud0310 commented Sep 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rami3l commented Sep 12, 2026

Uh oh!

rami3l Sep 14, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Cloud0310 Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

Cloud0310 commented Sep 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Cloud0310 commented Sep 5, 2026 •

edited

Loading

Cloud0310 commented Sep 6, 2026 •

edited

Loading

djc commented Sep 6, 2026 •

edited

Loading

rami3l commented Sep 6, 2026 •

edited

Loading

rami3l commented Sep 6, 2026 •

edited

Loading

rami3l commented Sep 7, 2026 •

edited

Loading

rami3l commented Sep 7, 2026 •

edited

Loading

Cloud0310 commented Sep 7, 2026 •

edited

Loading

Cloud0310 commented Sep 12, 2026 •

edited

Loading

rami3l Sep 14, 2026 •

edited by rustbot

Loading