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

could not find cargo home dir

Error message

could not find cargo home dir

What it means

Returned by `cargo_home_with_cwd_env` (crates/home/src/env.rs:79) when `CARGO_HOME` is unset/empty AND `home_dir_with_env` returns `None`. Cargo needs a writable home base (`~/.cargo`) for its registry cache, git checkouts, and config; with no home directory resolvable it cannot proceed and raises this io::Error.

Source

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

/// 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 cargo_home_with_cwd_env(env: &dyn Env, cwd: &Path) -> io::Result<PathBuf> {
    match env.var_os("CARGO_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(|p| p.join(".cargo"))
            .ok_or_else(|| io::Error::new(io::ErrorKind::Other, "could not find cargo home dir")),
    }
}

/// 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_env(env: &dyn Env) -> io::Result<PathBuf> {
    let cwd = env.current_dir()?;
    rustup_home_with_cwd_env(env, &cwd)
}

/// Variant of `cargo_home_with_cwd` where the environment source is
/// parameterized.
///
/// This is specifically to support in-process testing scenarios

View on GitHub (pinned to 0e07a15537)

Solutions

1. Set `CARGO_HOME` to an absolute, writable path before invoking cargo (e.g. `export CARGO_HOME=/tmp/cargo-home`).
2. Set `HOME` to a valid, writable directory so `home_dir()` resolves.
3. For containers, ensure the runtime user has a passwd entry (`useradd`) or run with a real home dir.

Example fix

# before — container with no HOME / passwd entry
RUN cargo build
# after
ENV CARGO_HOME=/usr/local/cargo
RUN mkdir -p $CARGO_HOME && cargo build

fn cargo_home_resolvable() -> bool {
    std::env::var_os("CARGO_HOME").filter(|s| !s.is_empty()).is_some() || std::env::home_dir().is_some()
}
// assert cargo_home_resolvable() before running cargo

When it happens

Trigger: `CARGO_HOME` is not set (or empty) and the OS reports no home directory — `std::env::home_dir()` returns `None`. Common in containers/CI running as a user with no passwd entry, or in sandboxed daemons.

Common situations: Docker images running cargo as a UID with no `/etc/passwd` entry; `HOME` unset in systemd units or cron; minimal scratch containers; chroot/nobody-user builds; hardened sandboxes that strip `HOME`.

Related errors

• could not find rustup home dir
• no executable for `{}` found in PATH
• Cargo couldn't find your home directory. This probably means
• not implemented
• argument for --color must be auto, always, or never, but fou

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