Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
cargo new hello          # binary package in ./hello
cargo new --lib mylib    # library package in ./mylib
cd existing-folder && cargo init

Try it

Rust The generated main.rs

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.

Rust What the library template gives you

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

Terminal
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 new fails if the target directory already exists; cargo init fails if Cargo.toml already exists. Neither overwrites your files.
  • Package names with hyphens are fine (my-app), but inside Rust code the crate is called my_app.
  • Within a workspace, cargo new adds the new member to the root Cargo.toml automatically.
  • Use cargo new once per project; to add a second binary later, create src/bin/other.rs or 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 under tests/ to exercise it.
  • Reserved names such as test, core, std and Windows device names (nul, con) are rejected as package names.