{"record":{"id":"39bd4e01d2c2b106","repo":"rust-lang/cargo","slug":"cannot-create-package-in-the-home-directory-help","errorCode":null,"errorMessage":"cannot create package in the home directory\n\nhelp: use `cargo init <path>` to create a package in a different directory","messagePattern":"cannot create package in the home directory\n\nhelp: use `cargo init <path>` to create a package in a different directory","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/ops/cargo_new.rs","lineNumber":452,"sourceCode":"            \"failed to create package `{}` at `{}`\",\n            name,\n            path.display()\n        )\n    })?;\n    Ok(())\n}\n\npub fn init(opts: &NewOptions, gctx: &GlobalContext) -> CargoResult<NewProjectKind> {\n    // This is here just as a random location to exercise the internal error handling.\n    if gctx.get_env_os(\"__CARGO_TEST_INTERNAL_ERROR\").is_some() {\n        return Err(crate::util::internal(\"internal error test\"));\n    }\n\n    let path = &opts.path;\n\n    if let Some(home) = home_dir() {\n        if path == &home {\n            anyhow::bail!(\n                \"cannot create package in the home directory\\n\\n\\\n                 help: use `cargo init <path>` to create a package in a different directory\"\n            )\n        }\n    }\n    let name = get_name(path, opts)?;\n    let mut src_paths_types = vec![];\n    detect_source_paths_and_types(path, name, &mut src_paths_types)?;\n    let kind = calculate_new_project_kind(opts.kind, opts.auto_detect_kind, &src_paths_types);\n    gctx.shell()\n        .status(\"Creating\", format!(\"{} package\", opts.kind))?;\n\n    if path.join(\"Cargo.toml\").exists() {\n        anyhow::bail!(\n            \"`cargo init` cannot be run on existing Cargo packages\\n\\\n             help: use `cargo new` to create a package in a new subdirectory\"\n        )\n    }","sourceCodeStart":434,"sourceCodeEnd":470,"githubUrl":"https://github.com/rust-lang/cargo/blob/98a09e7e7d62850f14e5b6132101fc1edd19a16f/src/ops/cargo_new.rs#L434-L470","documentation":"`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.","triggerScenarios":"Running `cargo init` with no argument from `$HOME`, or `cargo init ~`, or `cargo init $HOME`. Any path that resolves equal to the home directory.","commonSituations":"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.","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."],"exampleFix":"# before\n$ cd ~ && cargo init   # error: cannot create package in the home directory\n\n# after\n$ cargo init myproject   # or:\n$ cargo new myproject","handlingStrategy":"validation","validationCode":"use std::path::Path;\nfn is_home(path: &Path, home: &Path) -> bool { path == home }\n// if is_home(&target, &home_dir) { reject with a hint to use a subdirectory }","typeGuard":"fn is_not_home_dir(path: &Path, home: &Path) -> bool { path != home }","tryCatchPattern":null,"preventionTips":["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."],"tags":["cargo-init","home-directory","filesystem","cli-usage"],"backgroundTag":null,"analyzedSha":"98a09e7e7d62850f14e5b6132101fc1edd19a16f","analyzedAt":"2026-08-11T17:42:36.556Z","contentChangedAt":"2026-08-11T17:42:36.556Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}