cargo-new

Create a new Rust project with a binary target

$ cargo new [path/to/directory]

cargo new [OPTIONS] <path>

--bin
    Create a binary (executable) project (default)

--lib
    Create a library project

--edition <EDITION>
    Rust edition to use (2015, 2018, 2021, 2024; default: 2021)

--name <NAME>
    Set the resulting crate name (overrides directory name)

--vcs <VCS>
    Initialize VCS repo: git (default), hg, pijul, fossil, none

--registry <REGISTRY>
    Registry to use for Cargo.toml

-q, --quiet
    Do not print cargo log messages

-v, --verbose
    Use verbose output (-vv very verbose)

--color <WHEN>
    Control when to use color: auto, always, never

--frozen
    Require Cargo.lock and cache are up to date

--locked
    Require Cargo.lock is up to date

--offline
    Operate without network access

--config <KEY=VAL>
    Override config value

cargo new is a command from Cargo, Rust's package manager and build tool. It initializes a new Rust project (crate) in the specified directory. By default, it creates a binary executable project with a Cargo.toml manifest file containing package metadata, a src/main.rs source file with a basic "Hello, world!" program, and initializes a Git repository (including .gitignore). It supports creating library projects instead, setting specific crate names, Rust editions (e.g., 2021, 2024), and various version control systems.

This command streamlines project setup, ensuring standard structure for Cargo workspaces, dependencies, and builds. It's ideal for starting new applications or libraries, automatically handling boilerplate so developers can focus on coding. Options allow customization without manual file creation.

Requires Git if --vcs git (default). Fails if path exists and is non-empty. Crate name derived from path unless --name used; invalid names cause errors.

cargo new hello # Binary project
cargo new --lib mylib # Library
cargo new --vcs none foo # No VCS

Cargo.toml, src/main.rs or lib.rs, .gitignore, Cargo.lock (binary only), VCS repo.

Introduced with Cargo in 2014 by Mozilla's Servo team. Evolved with Rust editions (2018+) and VCS support expansions (pijul, fossil in recent versions). Core to Rust ecosystem since Rust 1.0.

cargo(1), git-init(1), cargo-init(1)