CARGO-NEW(1)

📦 version 1.78.0, in ubuntu jammy, ubuntu noble

💖 CARGO-NEW — Create a New Cargo Package 💖

okay bestie, welcome to cargo-new(1), straight out of the General Commands Manual 🎀 this is the one that spins up a whole brand-new Cargo package for you, like, from absolutely nothing. iconic behavior fr fr.

✨ SYNOPSIS ✨

cargo new [options] path

🦋 DESCRIPTION 🦋

so the way this works: this command creates a shiny new Cargo package in the directory you point it at. it's giving starter pack — you get a lil template with a Cargo.toml manifest, a sample source file, and a VCS ignore file. 🫶

and if that directory isn't already chillin' inside a VCS repository? boom, a new repository gets created for you (peep --vcs down below for the deets).

💡 if you wanna create a new manifest inside a directory that already exists, that's a whole different vibe — go check cargo-init(1), it's the sibling command bestie.

👑 OPTIONS 👑

🌸 New Options 🌸

  • --bin — makes a package with a binary target (src/main.rs). and ngl, this is the default behavior, so if you do nothing you already get this one. slay.
  • --lib — makes a package with a library target (src/lib.rs).
  • --edition edition — pick which Rust edition you want. default is 2021. the possible values are: 2015, 2018, 2021, 2024. choose your fighter 💅
  • --name name — sets the package name. if you don't say anything, it defaults to the directory name.
  • --vcs vcs — initializes a new VCS repository for whichever version control system you name (git, hg, pijul, or fossil), or initializes no version control at all (none). if you don't specify it, it defaults to git or the config value cargo-new.vcs, or none if you're already inside a VCS repository. iykyk.
  • --registry registry — this sets the publish field in Cargo.toml to whatever registry name you give it, which restricts publishing to only that registry. registry names are defined in Cargo config files (https://doc.rust-lang.org/cargo/reference/config.html). if you don't specify one, the default registry defined by the registry.default config key gets used. and if the default registry isn't set and you didn't pass --registry, then the publish field just doesn't get set at all, which means publishing won't be restricted. 🍓

🎀 Display Options 🎀

  • -v, --verbose — use verbose output. you can specify it twice for "very verbose" output, which includes extra output like dependency warnings and build script output. can also be set with the term.verbose config value (https://doc.rust-lang.org/cargo/reference/config.html). talkative queen ✨
  • -q, --quiet — do not print cargo log messages. can also be set with the term.quiet config value (https://doc.rust-lang.org/cargo/reference/config.html). silence, but make it chic 🤫
  • --color when — controls when colored output is used. valid values:
    • auto (default): automatically detect if color support is available on the terminal.
    • always: always display colors. 🌈
    • never: never display colors.

can also be set with the term.color config value (https://doc.rust-lang.org/cargo/reference/config.html).

💜 Common Options 💜

  • +toolchain — if Cargo was installed with rustup, and the first argument to cargo starts with +, it gets interpreted as a rustup toolchain name (like +stable or +nightly). see the rustup documentation (https://rust-lang.github.io/rustup/overrides.html) for more info on how toolchain overrides work.
  • --config KEY=VALUE or PATH — overrides a Cargo configuration value. the argument should be in TOML syntax of KEY=VALUE, or given as a path to an extra configuration file. this flag can be specified multiple times. see the command-line overrides section (https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides) for more.
  • -C PATH — changes the current working directory before executing any specified operations. this affects stuff like where cargo looks by default for the project manifest (Cargo.toml), and also the directories it searches when discovering .cargo/config.toml, for example. this option must appear before the command name, like cargo -C path/to/my-project build.
⚠️ heads up bestie, this option is only available on the nightly channel (https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) and it requires the -Z unstable-options flag to enable (see #10098 at https://github.com/rust-lang/cargo/issues/10098). no cap.
  • -h, --help — prints help information.
  • -Z flag — unstable (nightly-only) flags to Cargo. run cargo -Z help for details. 🔥

🌈 ENVIRONMENT 🌈

see the reference (https://doc.rust-lang.org/cargo/reference/environment-variables.html) for all the details on environment variables that Cargo reads. the lore is all there, go read it 🧚

⭐ EXIT STATUS ⭐

  • 0: Cargo succeeded. 🎉
  • 101: Cargo failed to complete. 😭

🌸 EXAMPLES 🌸

  1. create a binary Cargo package in the given directory:
cargo new foo

🫶 SEE ALSO 🫶

cargo(1), cargo-init(1)

and that's the whole page, bestie 💅 this was CARGO-NEW(1) from the General Commands Manual, dated CARGO-NEW(1) — okay so the footer literally just says the page name again, which is very main character of it. go forth and cargo new something iconic 👑✨

📦 where this page comes from