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

could not find cargo home dir

Error message

could not find cargo home dir

What it means

`cargo_home_with_cwd_env` resolves the Cargo home directory. If `CARGO_HOME` is set and non-empty it is used (joined to cwd if relative); otherwise it falls back to `home_dir_with_env(env)` appended with `.cargo`. If the home directory cannot be determined (the OS/env provides no home), the function returns an `io::Error` (kind `Other`, message `"could not find cargo home dir"`). Cargo cannot locate its registry/cache/store without this.

Solutions

1. Set `CARGO_HOME` explicitly to an absolute, writable directory (e.g. `export CARGO_HOME=/path/to/.cargo`).
2. Ensure `HOME` (Unix) or `USERPROFILE` (Windows) is set to a valid, accessible home directory.
3. For service/cron contexts, define `CARGO_HOME` (and `HOME`) in the unit/environment file.

Example fix

# before (env scrubbed, no HOME/CARGO_HOME)
cargo build  # -> could not find cargo home dir

# after
export CARGO_HOME=/var/lib/ci/.cargo
export HOME=/var/lib/ci
cargo build

use std::path::PathBuf;
fn resolve_cargo_home() -> Result<PathBuf, String> {
    if let Ok(h) = std::env::var("CARGO_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(".cargo")); } }
    Err("set CARGO_HOME or HOME".into())
}
// ensure this returns Ok before invoking Cargo-dependent code

When it happens

Trigger: Running Cargo (or a library resolving cargo home) in an environment where `CARGO_HOME` is unset/empty AND the home directory cannot be derived from env vars (`HOME` on Unix, `USERPROFILE`/tokens on Windows) via `home_dir_with_env`. Returns `Err`.

Common situations: Minimal containers/sandboxes without `HOME` set, systemd services or cron jobs with a cleared environment, running as a user with no home directory entry, or test harnesses that scrub environment variables.

Related errors

• could not find rustup home dir
• 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`
• Cargo couldn't find your home directory. This probably…

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

Appendix: 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 eb98b54bc9)