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

could not find rustup home dir

Error message

could not find rustup home dir

What it means

Returned by `rustup_home_with_cwd_env` (crates/home/src/env.rs:112) when `RUSTUP_HOME` is unset/empty AND `home_dir_with_env()` returns `None`. Rustup stores toolchains under `~/.rustup`; without a home dir cargo cannot locate the active toolchain and bails.

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 0e07a15537)

Solutions

1. Set `RUSTUP_HOME` to the absolute path of the rustup home (e.g. `export RUSTUP_HOME=/opt/rustup`).
2. Ensure `HOME` points to a writable directory so `~/.rustup` resolves.
3. Give the runtime user a real passwd entry (`useradd -m`) in containers.

Example fix

# before
RUN cargo build
# after
ENV RUSTUP_HOME=/usr/local/rustup CARGO_HOME=/usr/local/cargo HOME=/tmp
RUN cargo build

fn rustup_home_resolvable() -> bool {
    std::env::var_os("RUSTUP_HOME").filter(|s| !s.is_empty()).is_some() || std::env::home_dir().is_some()
}
// assert rustup_home_resolvable() before invoking rustup-managed cargo

When it happens

Trigger: `RUSTUP_HOME` unset and no resolvable home directory (`std::env::home_dir() -> None`), typically in containers or daemons missing a passwd entry or `HOME`.

Common situations: Slim Docker images invoking rustup-managed cargo without `HOME` or `RUSTUP_HOME`; CI runners as a numeric UID with no passwd; systemd services with `HOME=` cleared; chroot builds.

Related errors

• could not find cargo home dir
• no executable for `{}` found in PATH
• invalid character `+` in package name: `+{toolchain}` Us
• probably rustup rustc, but without rustup's env vars
• not implemented

AI-assisted analysis of rust-lang/cargo@0e07a15537 (2026-08-06). Data as JSON: /data/errors/0b7faf657ccf247b.json. Report an issue: GitHub.