rust-lang/cargo · error

Cargo couldn't find your home directory. This probably means

Error message

Cargo couldn't find your home directory. This probably means that $HOME was not set.

What it means

GlobalContext::default (mod.rs:423-434) computes the user's home directory via the homedir() helper; if it returns None it bails 'Cargo couldn't find your home directory. This probably means that $HOME was not set.' Cargo needs the home dir for $CARGO_HOME config, the global cache, and credentials.

Source

Thrown at src/context/mod.rs:428

            progress_config: ProgressConfig::default(),
            env_config: Default::default(),
            nightly_features_allowed: matches!(&*features::channel(), "nightly" | "dev"),
            ws_roots: Default::default(),
            global_cache_tracker: Default::default(),
            deferred_global_last_use: Default::default(),
        }
    }

    /// Creates a new instance, with all default settings.
    ///
    /// This does only minimal initialization. In particular, it does not load
    /// any config files from disk. Those will be loaded lazily as-needed.
    pub fn default() -> CargoResult<GlobalContext> {
        let shell = Shell::new();
        let cwd =
            env::current_dir().context("couldn't get the current directory of the process")?;
        let homedir = homedir(&cwd).ok_or_else(|| {
            anyhow!(
                "Cargo couldn't find your home directory. \
                 This probably means that $HOME was not set."
            )
        })?;
        Ok(GlobalContext::new(shell, cwd, homedir))
    }

    /// Gets the user's Cargo home directory (OS-dependent).
    pub fn home(&self) -> &Filesystem {
        &self.home_path
    }

    /// Returns a path to display to the user with the location of their home
    /// config file (to only be used for displaying a diagnostics suggestion,
    /// such as recommending where to add a config value).
    pub fn diagnostic_home_config(&self) -> String {
        let home = self.home_path.as_path_unlocked();
        let path = match self.get_file_path(home, "config", false) {

View on GitHub (pinned to 0e07a15537)

Solutions

1. Ensure $HOME (Unix) / %USERPROFILE% (Windows) is set for the user running cargo.
2. Set CARGO_HOME explicitly to a writable directory as a substitute.
3. For services, define the env in the unit file (`Environment=HOME=/...`).

Example fix

# before (container/service with cleared env)
cargo build   # HOME unset -> error
# after
export HOME=/tmp/fakehome
cargo build   # or: export CARGO_HOME=/tmp/cargo-home

# Ensure HOME is set before any cargo invocation in minimal environments:
: "${HOME:=/tmp/fakehome}"; export HOME
: "${CARGO_HOME:=$HOME/.cargo}"; export CARGO_HOME
cargo build

When it happens

Trigger: Constructing a GlobalContext (e.g. embedding cargo as a library, or running the cargo binary) in an environment where no home directory can be determined (HOME unset on Unix and the passwd DB unavailable; or USERPROFILE/uname unavailable on Windows).

Common situations: Containers/minimal images that clear HOME; systemd services or cron jobs without a login shell; sandboxed test harnesses that wipe the environment.

Related errors

• {key:?} could not be found in the environment snapshot
• could not find cargo home dir
• no executable for `{}` found in PATH
• subcommand is required, add a subcommand to the command alia
• alias {} has unresolvable recursive definition: {} -> {}

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