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

cannot create package in the home directory help: use `carg

Error message

cannot create package in the home directory

help: use `cargo init <path>` to create a package in a different directory

What it means

The `init` command explicitly forbids operating on the user's home directory because scaffolding Cargo files directly in $HOME would pollute it with a Cargo.toml, target/, src/, etc. When path == home_dir() (cargo_new.rs:502), Cargo bails and suggests running `cargo init <subpath>` to target a dedicated directory.

Source

Thrown at src/ops/cargo_new.rs:503

            "failed to create package `{}` at `{}`",
            name,
            path.display()
        )
    })?;
    Ok(())
}

pub fn init(opts: &NewOptions, gctx: &GlobalContext) -> CargoResult<NewProjectKind> {
    // This is here just as a random location to exercise the internal error handling.
    if gctx.get_env_os("__CARGO_TEST_INTERNAL_ERROR").is_some() {
        return Err(crate::util::internal("internal error test"));
    }

    let path = &opts.path;

    if let Some(home) = home_dir() {
        if path == &home {
            anyhow::bail!(
                "cannot create package in the home directory\n\n\
                 help: use `cargo init <path>` to create a package in a different directory"
            )
        }
    }
    let name = get_name(path, opts)?;
    let mut src_paths_types = vec![];
    detect_source_paths_and_types(path, name, &mut src_paths_types)?;
    let kind = calculate_new_project_kind(opts.kind, opts.auto_detect_kind, &src_paths_types);
    gctx.shell()
        .status("Creating", format!("{} package", opts.kind))?;

    if path.join("Cargo.toml").exists() {
        anyhow::bail!(
            "`cargo init` cannot be run on existing Cargo packages\n\
             help: use `cargo new` to create a package in a new subdirectory"
        )
    }

View on GitHub (pinned to 0e07a15537)

Solutions

1. Create and target a subdirectory: `mkdir myproj && cargo init myproj`
2. cd into a project folder before running `cargo init`
3. Use `cargo new myproj` instead, which creates the directory for you

Example fix

# before (cwd is $HOME)
cargo init
# after
mkdir myproj && cargo init myproj

use std::path::Path;
fn ensure_not_home(path: &Path) -> Result<(), String> {
    let home = std::env::var_os("HOME").or(std::env::var_os("USERPROFILE"));
    if home.map(|h| path == Path::new(&h)).unwrap_or(false) {
        Err("cannot init the home directory; pick a subdirectory".into())
    } else { Ok(()) }
}

ensure_not_home(path)?;

import { homedir } from 'os';
import { resolve } from 'path';
function isNotHome(path: string): boolean { return resolve(path) !== homedir(); }

When it happens

Trigger: `cargo init` with no path while cwd is $HOME; `cargo init ~`/`cargo init $HOME`; programmatically calling init with path set to home_dir().

Common situations: Running `cargo init` right after opening a fresh terminal that starts in $HOME; CI containers whose default cwd is /root or /home/user; misconfigured editor that opens at home and triggers an init command.

Related errors

• cannot clean `{}`: not a directory
• `cargo init` cannot be run on existing Cargo packages help:
• Cargo couldn't find your home directory. This probably means
• cannot clean `{}`: {err}
• failed to open `{}`: {}

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