Rust Reference ยท Tools
cargo new and cargo init
Reference for cargo new and cargo init: creating binary and library packages, --lib, --name, --edition, --vcs, the generated files and workspace behavior.
cargo new creates a new Rust package in a fresh directory. cargo init does the same inside a directory that already exists, which is handy when you have started a folder or cloned an empty repository. Both write a Cargo.toml manifest and a starter source file, and (unless told otherwise) set up a Git repository with a .gitignore that excludes target/.
By default the package is a binary with a src/main.rs that prints "Hello, world!". Pass --lib to get a library with src/lib.rs instead. These are command-line tools, so the examples are read-only; the runnable block below shows the program that cargo new generates.
cargo new hello # binary package in ./hello cargo new --lib mylib # library package in ./mylib cd existing-folder && cargo init
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
cargo new [options] <path> cargo init [options] [path]
| Option | Description |
|---|---|
--bin |
Create a binary package (the default). |
--lib |
Create a library package with src/lib.rs. |
--name <name> |
Package name. Defaults to the directory name; must be a valid crate name (letters, digits, - and _, not starting with a digit). |
--edition <year> |
Edition written to Cargo.toml. The default is the newest edition the installed Cargo knows. |
--vcs git or hg or pijul or fossil or none |
Version control to initialize. none skips it. Git is skipped if you are already inside a repository. |
--registry <name> |
Registry to put in the publish field. |
-q, -v |
Less or more output. |
The generated files
| File | Purpose |
|---|---|
Cargo.toml |
The manifest: [package] with name, version = "0.1.0", edition, and an empty [dependencies]. |
src/main.rs or src/lib.rs |
The crate root. |
.gitignore |
Ignores /target (plus Cargo.lock for libraries in older Cargo versions). |
.git/ |
Created unless --vcs none or you are inside an existing repository. |
Usage notes
cargo newfails if the target directory already exists;cargo initfails ifCargo.tomlalready exists. Neither overwrites your files.- Package names with hyphens are fine (
my-app), but inside Rust code the crate is calledmy_app. - Within a workspace,
cargo newadds the new member to the rootCargo.tomlautomatically. - Use
cargo newonce per project; to add a second binary later, createsrc/bin/other.rsor declare[[bin]]targets in the manifest. - Cargo reads defaults for author and VCS settings from the user's configuration (
~/.cargo/config.toml,[cargo-new]table). - A library crate does not run on its own. Put examples under
examples/and tests undertests/to exercise it. - Reserved names such as
test,core,stdand Windows device names (nul,con) are rejected as package names.