What causes "failed to determine the Cargo bin directory" in sxyazi/yazi?

Set `CARGO_HOME` (e.g. `export CARGO_HOME=$HOME/.cargo`) before running `cargo yazi install`.

failed to determine the Cargo bin directory

Error message

failed to determine the Cargo bin directory

What it means

`cargo_bin_dir` resolves the directory where `cargo install` places binaries: first from `CARGO_INSTALL_ROOT`, then from `CARGO_HOME` or `HOME`/`USERPROFILE` (via `cargo_home_dir`), appending `bin` in each case. If none of these environment variables is set, it bails because it cannot determine where the binary should be installed.

Source

Thrown at yazi-build/src/common.rs:14

use std::{env, ffi::OsString, fs, path::{Path, PathBuf}, process::Command};

use anyhow::{Context, Result, bail, ensure};

pub(super) fn cargo() -> OsString { env::var_os("CARGO").unwrap_or_else(|| "cargo".into()) }

pub(super) fn cargo_bin_dir() -> Result<PathBuf> {
	if let Some(root) = env::var_os("CARGO_INSTALL_ROOT") {
		return Ok(PathBuf::from(root).join("bin"));
	}
	if let Some(home) = cargo_home_dir() {
		return Ok(home.join("bin"));
	}
	bail!("failed to determine the Cargo bin directory")
}

fn cargo_home_dir() -> Option<PathBuf> {
	env::var_os("CARGO_HOME").map(PathBuf::from).or_else(|| {
		env::var_os("HOME")
			.or_else(|| env::var_os("USERPROFILE"))
			.map(|home| PathBuf::from(home).join(".cargo"))
	})
}

pub(super) fn workspace_root() -> Result<PathBuf> {
	Path::new(env!("CARGO_MANIFEST_DIR"))
		.parent()
		.map(Path::to_owned)
		.context("yazi-build must be inside the Yazi workspace")
}

pub(super) fn is_linux_target(target: &str) -> bool {

View on GitHub (pinned to 5f901b886b)

Solutions

Set `CARGO_HOME` (e.g. `export CARGO_HOME=$HOME/.cargo`) before running `cargo yazi install`.
Set `CARGO_INSTALL_ROOT` to an explicit install root (e.g. `/usr/local`) to bypass home detection entirely.
Ensure `HOME` (Unix) or `USERPROFILE` (Windows) is present in the execution environment.

Example fix

// before (Dockerfile)
RUN cargo yazi install
// after
RUN CARGO_HOME=/usr/local/cargo cargo yazi install --bin-dir /usr/local/bin

Defensive patterns

Strategy: validation

Validate before calling

if [ -z "$CARGO_HOME" ] && [ -z "$CARGO_INSTALL_ROOT" ] && [ -z "$HOME" ] && [ -z "$USERPROFILE" ]; then
  echo "set CARGO_HOME before running cargo yazi install" >&2; exit 1;
fi

Try / catch

match cargo_bin_dir() {
  Ok(dir) => dir,
  Err(_) => {
    eprintln!("set CARGO_HOME or CARGO_INSTALL_ROOT and retry");
    std::process::exit(1);
  }
}

Prevention

Set CARGO_HOME explicitly in Dockerfiles, CI jobs, and service units.
Use CARGO_INSTALL_ROOT for non-interactive installs to a fixed path.
Sanity-check `echo $HOME` in minimal environments before installing.

When it happens

Trigger: Running the `install` task (`cargo yazi install`) in an environment with none of `CARGO_INSTALL_ROOT`, `CARGO_HOME`, `HOME`, or `USERPROFILE` set — e.g. a stripped-down container, systemd service, or CI job with a minimal env.

Common situations: Docker builds with `ENV` cleared; cron/systemd units lacking `$HOME`; running under `env -i`; Windows CI missing `USERPROFILE`.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of sxyazi/yazi@5f901b886b (2026-09-02). Data as JSON: /api/errors/76d950523a507e26. Report an issue: GitHub.