What causes "cannot create package in the home directory help: use `cargo init ` to create a package in a different directory" in rust-lang/cargo?

Create and init a subdirectory: `mkdir myproject && cargo init myproject` (or `cargo new myproject`).

cannot create package in the home directory help: use…

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

`cargo init` refuses to operate on the user's home directory itself. Initializing cargo's config root as a package would pollute `$HOME` with `Cargo.toml`/`src/` and break global config assumptions. The check compares `opts.path` against `home_dir()` and bails with guidance to use `cargo init <path>` for a real subdirectory.

Solutions

Create and init a subdirectory: `mkdir myproject && cargo init myproject` (or `cargo new myproject`).
Change to the intended project directory before running `cargo init`.
Ensure scripts pass an explicit non-home path.

Example fix

# before
$ cd ~ && cargo init   # error: cannot create package in the home directory

# after
$ cargo init myproject   # or:
$ cargo new myproject

Defensive patterns

Strategy: validation

Validate before calling

use std::path::Path;
fn is_home(path: &Path, home: &Path) -> bool { path == home }
// if is_home(&target, &home_dir) { reject with a hint to use a subdirectory }

Type guard

fn is_not_home_dir(path: &Path, home: &Path) -> bool { path != home }

Prevention

Never run `cargo init` from `$HOME`; always target a project subdirectory.
In scripts, resolve and assert the target path differs from home before invoking.
Teach new users that `~` is off-limits as a package root.

When it happens

Trigger: Running `cargo init` with no argument from `$HOME`, or `cargo init ~`, or `cargo init $HOME`. Any path that resolves equal to the home directory.

Common situations: New users opening a terminal at `~` and running `cargo init`. CI shells that start in `$HOME`. Misconfigured scaffolding tools that pass `$HOME` as the path.

Related errors

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

Appendix: source

Thrown at src/ops/cargo_new.rs:452

            "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 98a09e7e7d)