CARGO-NEW(1)

💖 CARGO-NEW(1) 💖

okay bestie, welcome to the General Commands Manual page for cargo-new, section 1, and honestly? it's giving "starter pack but make it official." let's get into it 🫶

---

✨ NAME ✨

cargo-new — Create a new Cargo package

like. it makes you a whole new Cargo package. brand new. fresh out the box. 🌸

---

🌈 SYNOPSIS 🌈

cargo new [options] path

that's it. that's the whole vibe. cargo new, some optional flags, and a path. slay.

---

🦋 DESCRIPTION 🦋

so when you run this command, it creates a new Cargo package in whatever directory you point it at. and not just an empty folder, no no — it comes with a simple template: a Cargo.toml manifest, a sample source file, and a VCS ignore file. a whole lil starter kit. iconic. ✨

and here's the tea: if the directory is not already inside a VCS repository, then a brand new repository gets created for you (peep --vcs down below to control that 👀).

also, if you want the similar but different version of this — the one that creates a new manifest inside a directory that already exists — go check out cargo-init(1). sibling energy fr fr.

---

💅 OPTIONS 💅

🎀 New Options 🎀

• --bin — create a package with a binary target (src/main.rs). lowkey this is the default behavior, so if you do nothing, you get a binary. main character energy from the jump.
• --lib — create a package with a library target (src/lib.rs). for when you're in your library era 📚
• --edition edition — specify which Rust edition to use. default is 2024. possible values: 2015, 2018, 2021, 2024. pick your era bestie, there are literally four of them.
• --name name — set the package name. if you don't, it defaults to the directory name. no thoughts, just folder name. 🙈
• --vcs vcs — initialize a new VCS repository for the given version control system. your options are git, hg, pijul, or fossil — or you can say none and not initialize any version control at all. if you don't specify anything, it defaults to git or the configuration value cargo-new.vcs, or none if you're already inside a VCS repository. it's giving "it depends" but in a helpful way.
• --registry registry — this sets the publish field in Cargo.toml to the given registry name, 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 use --registry? then the publish field just won't be set at all, which means publishing won't be restricted. freedom, basically. 🦋

🔥 Display Options 🔥

• -v, --verbose — use verbose output. and yes, you can specify it twice for "very verbose" output, which includes extra output such as dependency warnings and build script output. double it and give it to the next person. may also be specified with the term.verbose config value <https://doc.rust-lang.org/cargo/reference/config.html>.
• -q, --quiet — do not print cargo log messages. silent mode. stealth mode. ninja mode. 🥷 may also be specified with the term.quiet config value <https://doc.rust-lang.org/cargo/reference/config.html>.
• --color when — control when colored output is used. valid values:
  • auto (default): automatically detect if color support is available on the terminal. it just knows. 🔮
  • always: always display colors. rainbow mode, no apologies. 🌈
  • never: never display colors. monochrome moment.

may also be specified with the term.color config value <https://doc.rust-lang.org/cargo/reference/config.html>.

👑 Common Options 👑

• +toolchain — if Cargo has been installed with rustup, and the first argument to cargo begins with +, it will be interpreted as a rustup toolchain name (such as +stable or +nightly). see the rustup documentation <https://rust-lang.github.io/rustup/overrides.html> for more info about how toolchain overrides work. it's giving "choose your fighter." ⭐
• --config KEY=VALUE or PATH — overrides a Cargo configuration value. the argument should be in TOML syntax of KEY=VALUE, or provided as a path to an extra configuration file. this flag may be specified multiple times. see the command-line overrides section <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> for more info.
• -C PATH — changes the current working directory before executing any specified operations. this affects things like where cargo looks by default for the project manifest (Cargo.toml), as well as the directories searched for discovering .cargo/config.toml, for example. this option must appear before the command name, for example cargo -C path/to/my-project build. order matters bestie, don't test me on this one. 😭

this option is only available on the nightly channel <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and requires the -Z unstable-options flag to enable (see #10098 <https://github.com/rust-lang/cargo/issues/10098>). so like. not for everybody yet. 🫶

• -h, --help — prints help information. when in doubt, ask for help. no shame. 💜
• -Z flag — unstable (nightly-only) flags to Cargo. run cargo -Z help for details. the forbidden knowledge section. 🧚

---

🌸 ENVIRONMENT 🌸

see the reference <https://doc.rust-lang.org/cargo/reference/environment-variables.html> for details on environment variables that Cargo reads. there's a whole world of env vars out there, iykyk.

---

⭐ EXIT STATUS ⭐

• 0: Cargo succeeded. 🎉 we ate.
• 101: Cargo failed to complete. 💀 not the vibe.

---

🍓 EXAMPLES 🍓

1. Create a binary Cargo package in the given directory:

cargo new foo

boom. foo. done. periodt. 💅

---

💜 SEE ALSO 💜

cargo(1), cargo-init(1)

---

and that's the whole page bestie!! this was CARGO-NEW(1) from the General Commands Manual — go forth and make packages, you've got this 🫶✨🎀