/commands/cargo/cargo-new-project
cargo new: create a new Rust project (binary or library)
- tool
- Cargo
- versions
- Cargo 1.x, Rust 2024 edition
- os
- any
cargo new hello creates a folder hello with a Cargo.toml manifest, a src/main.rs that prints "Hello, world!", a .gitignore and a new Git repository: a ready-to-run binary package. Use cargo new --lib mylib for a library (src/lib.rs with a sample test) and cargo init to set up a package inside a folder that already exists.
Create a binary and a library
cargo new -q hello
cargo new -q --lib --vcs none mylib
find hello mylib -not -path '*/.git/*' -type f | sort
echo "--- hello/Cargo.toml"
cat hello/Cargo.toml
cd hello && cargo run -qOutput
hello/.gitignore hello/Cargo.toml hello/src/main.rs mylib/Cargo.toml mylib/src/lib.rs --- hello/Cargo.toml [package] name = "hello" version = "0.1.0" edition = "2024" [dependencies] Hello, world!
The binary package runs straight away with cargo run. -q hides the Creating binary (application) package messages. The library was created with --vcs none, so it has no .gitignore and no Git repository.
Options
| Command | What it does |
|---|---|
| cargo new hello | Binary package in a new folder, with Git (the default --bin) |
| cargo new --lib mylib | Library package with src/lib.rs |
| cargo new --vcs none hello | No Git repository and no .gitignore |
| cargo new --name app my-folder | Folder my-folder, package called app |
| cargo new --edition 2021 hello | Use an older Rust edition |
| cargo init | Turn the current folder into a package |
| cargo init --lib path/to/dir | Turn an existing folder into a library package |
| cargo new crates/core | Inside a workspace: creates the member and adds it to workspace.members |
Naming rules
Package names may contain letters, digits, - and _. A hyphen in the package name becomes an underscore in Rust code: package my-app is used as my_app in use statements. Cargo refuses names that are Rust keywords (fn, struct) and the name test, which conflicts with Rust's built-in test library; the error says that the folder name is used as the package name and suggests --name.
Pitfalls
- Inside another package. Running
cargo newinside a folder that belongs to a workspace adds the new package to that workspace; inside an unrelated package's folder, builds later fail with current package believes it's in a workspace when it's not. Create projects outside other packages, or add[workspace]to the newCargo.toml. - Running commands from the wrong folder.
cargo buildoutside the package folder fails with could not find Cargo.toml;cd hellofirst. - Folder already exists.
cargo newstops if the destination exists; usecargo initin that folder.
How to confirm it worked
cargo run inside a new binary package compiles it and prints Hello, world!; cargo test in a new library runs the sample it_works test. Then add dependencies with cargo add.
FAQ
What is the difference between cargo new and cargo init?
cargo new hello creates a new folder called hello. cargo init turns the current (or given) existing folder into a package, keeping files that are already there, such as an existing src/main.rs.
How do I create a project without a Git repository?
Pass --vcs none. By default cargo new initialises a Git repository and writes a .gitignore, unless the new folder is already inside a repository.
Which edition does cargo new use?
The newest stable edition the installed Cargo knows, which is 2024 for current toolchains. Pass --edition 2021 to choose an older one; the edition is recorded in Cargo.toml.