cargo-init

Initialize a Rust project with a binary target in the current directory

$ cargo init

$ cargo init [path/to/directory]

$ cargo init --lib

$ cargo init --vcs [git|hg|pijul|fossil|none]

$ cargo init --name [name]

cargo init [OPTIONS] [PATH]

--bin
    Create binary (default) project (mutually exclusive with --lib)

--lib
    Create library project (mutually exclusive with --bin)

--name
    Set package name, defaults to directory name

--vcs
    Initialize VCS: git, hg, pijul, none (default: git if available)

--edition
    Rust edition: 2015, 2018, 2021, 2024

--force
    Force overwrite of existing Cargo.toml or src directory

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

-q, --quiet
    No output printed to stdout

--color
    Control colors: auto, always, never

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

--locked
    Require Cargo.lock is up to date

-h, --help
    Print help information

-Z ...
    Unstable (nightly-only) flags

--help-verbose
    Help including unstable options

The cargo init command creates a new Rust package in an existing directory. Unlike cargo new, which creates a new directory, cargo init operates on the current or specified path, making it ideal for initializing projects in version control checkouts or existing folders.

It generates essential files: a Cargo.toml manifest with package metadata, and either src/main.rs for binaries or src/lib.rs for libraries. Dependencies like those in Cargo.toml are not fetched automatically; run cargo build afterward.

Supports specifying project type (binary or library), name, edition (e.g., 2021), and VCS integration (Git, etc.). Use --force to overwrite existing files. Perfect for quick setups in scripts or when directory structure already exists.

Does not create directory (use cargo new for that); VCS init may fail without tools installed; --force risks data loss.

cargo init --lib --name mylib creates library project named 'mylib'; cargo init ./myproj --git initializes Git repo.

Cargo.toml (manifest), .gitignore, src/main.rs or src/lib.rs; README.md optional via templates.

Introduced in Cargo 0.0.20 (2015); evolved with Rust editions and VCS support; maintained by Rust Project since Mozilla origins.

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