{"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":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/ops/cargo_new.rs","lineNumber":503,"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":485,"sourceCodeEnd":521,"githubUrl":"https://github.com/rust-lang/cargo/blob/0e07a155371a6ce88ae53a2c00df940280c09a67/src/ops/cargo_new.rs#L485-L521","documentation":"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.","triggerScenarios":"`cargo init` with no path while cwd is $HOME; `cargo init ~`/`cargo init $HOME`; programmatically calling init with path set to home_dir().","commonSituations":"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.","solutions":["Create and target a subdirectory: `mkdir myproj && cargo init myproj`","cd into a project folder before running `cargo init`","Use `cargo new myproj` instead, which creates the directory for you"],"exampleFix":"# before (cwd is $HOME)\ncargo init\n# after\nmkdir myproj && cargo init myproj","handlingStrategy":"validation","validationCode":"use std::path::Path;\nfn ensure_not_home(path: &Path) -> Result<(), String> {\n    let home = std::env::var_os(\"HOME\").or(std::env::var_os(\"USERPROFILE\"));\n    if home.map(|h| path == Path::new(&h)).unwrap_or(false) {\n        Err(\"cannot init the home directory; pick a subdirectory\".into())\n    } else { Ok(()) }\n}\n\nensure_not_home(path)?;","typeGuard":"import { homedir } from 'os';\nimport { resolve } from 'path';\nfunction isNotHome(path: string): boolean { return resolve(path) !== homedir(); }","tryCatchPattern":null,"preventionTips":["Never run `cargo init` from $HOME; cd into a project folder first","In wrapper scripts, reject paths equal to home_dir()","Configure shells/IDEs to open in a projects/ directory"],"tags":["cargo-init","filesystem","home-directory","safety"],"analyzedSha":"0e07a155371a6ce88ae53a2c00df940280c09a67","analyzedAt":"2026-08-06T01:46:58.334Z","schemaVersion":2}