rust-lang/cargo · error · io::Error

could not find rustup home dir

Error message

could not find rustup home dir

What it means

`rustup_home_with_cwd_env` mirrors the cargo-home logic for rustup. If `RUSTUP_HOME` is set and non-empty it is used (relative to cwd if not absolute); otherwise it falls back to `home_dir_with_env(env).join(".rustup")`. If no home directory can be determined, it returns an `io::Error` (kind `Other`, message `"could not find rustup home dir"`). This blocks rustup-managed toolchain resolution.

Solutions

1. Set `RUSTUP_HOME` to an absolute, writable directory (e.g. `export RUSTUP_HOME=/opt/rust/.rustup`).
2. Ensure `HOME` (Unix) or `USERPROFILE` (Windows) is set so the `.rustup` fallback resolves.
3. For containerized/service contexts, add `RUSTUP_HOME` and `HOME` to the environment definition.

Example fix

# before (minimal container, no HOME)
rustup show  # -> could not find rustup home dir

# after
export RUSTUP_HOME=/usr/local/rustup
export HOME=/root
rustup show

use std::path::PathBuf;
fn resolve_rustup_home() -> Result<PathBuf, String> {
    if let Ok(h) = std::env::var("RUSTUP_HOME") { if !h.is_empty() { return Ok(PathBuf::from(h)); } }
    if let Ok(h) = std::env::var("HOME") { if !h.is_empty() { return Ok(PathBuf::from(h).join(".rustup")); } }
    Err("set RUSTUP_HOME or HOME".into())
}
// ensure this returns Ok before invoking rustup-dependent code

When it happens

Trigger: Invoking code that resolves the rustup home in an environment where `RUSTUP_HOME` is unset/empty and `home_dir_with_env` returns `None` (no `HOME`/`USERPROFILE`). The `_ => home_dir_with_env(env)...ok_or_else(...)` arm fires.

Common situations: CI containers without `HOME`, hardened services, running under accounts lacking a passwd/home entry, or test environments that clear `RUSTUP_HOME` and `HOME` simultaneously.

Related errors

• could not find cargo home dir
• probably rustup rustc, but without rustup's env vars
• can't find library ` `, rename file to `src/lib.rs` or…
• cannot mix `proc-macro` crate type with others
• cannot specify both `metabuild` and `build`

AI-assisted analysis of rust-lang/cargo@eb98b54bc9 (2026-08-11). Data as JSON: /api/errors/0b7faf657ccf247b. Report an issue: GitHub.

Appendix: source

Thrown at crates/home/src/env.rs:112

/// Variant of `cargo_home_with_cwd` where the environment source is
/// parameterized.
///
/// This is specifically to support in-process testing scenarios
/// as environment variables and user home metadata are normally process global
/// state. See the `OsEnv` trait.
pub fn rustup_home_with_cwd_env(env: &dyn Env, cwd: &Path) -> io::Result<PathBuf> {
    match env.var_os("RUSTUP_HOME").filter(|h| !h.is_empty()) {
        Some(home) => {
            let home = PathBuf::from(home);
            if home.is_absolute() {
                Ok(home)
            } else {
                Ok(cwd.join(&home))
            }
        }
        _ => home_dir_with_env(env)
            .map(|d| d.join(".rustup"))
            .ok_or_else(|| io::Error::new(io::ErrorKind::Other, "could not find rustup home dir")),
    }
}

View on GitHub (pinned to eb98b54bc9)