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>]

-h, --help
    Prints help information.

-V, --version
    Prints version information.

--bin
    Creates a binary application (default).

--lib
    Creates a library project.

--vcs
    Initializes a new Git, Mercurial, Pijul, or Fossil repository, or none. Valid options: git, hg, pijul, fossil, none. Default is 'git'.

--edition
    Specifies the Rust edition to use for the new project (e.g., 2015, 2018, 2021). Defaults to the latest stable edition.

--name
    Sets the package name. By default, it derives the name from the directory name.


    The directory to initialize the project in. If omitted, the current directory is used.

cargo init is a fundamental command in the Rust ecosystem, used to set up the basic structure for a new Rust project within an existing or specified directory. Unlike `cargo new`, which creates a new directory and then initializes a project inside it, `cargo init` initializes a project in the current directory or a provided .

This command is essential for developers starting a new Rust application or library, providing a ready-to-use directory layout, a `Cargo.toml` manifest file, and a boilerplate source file (e.g., `src/main.rs` for binaries or `src/lib.rs` for libraries). The `Cargo.toml` file generated by `cargo init` acts as the project's manifest, defining its name, version, dependencies, and other metadata. By default, `cargo init` creates a binary application project, but it can be configured to create a library project using the `--lib` option. It also defaults to initializing a Git repository, which can be changed or disabled with the `--vcs` option. This command streamlines the project setup process, allowing developers to quickly begin writing Rust code without manually creating directories and files.

cargo init will not overwrite existing files in the target directory. If `Cargo.toml` or source files (`src/main.rs`, `src/lib.rs`) already exist, the command will fail to prevent accidental data loss.
The command cannot be run inside an existing Cargo project.
By default, it initializes a Git repository; ensure Git is installed if this behavior is desired or use `--vcs none` to disable it.

While both `cargo init` and `cargo new` create a new Rust project, `cargo new ` creates a new directory named `` and initializes the project inside it. In contrast, `cargo init []` initializes a project in the current directory if `` is omitted, or in the specified existing directory ``. Use `cargo init` when you already have a project folder and want to add Cargo support to it. Use `cargo new` when you want to start a completely fresh project in a brand new folder.

Upon successful execution, `cargo init` creates a standard Rust project structure:
- `Cargo.toml`: The project manifest file.
- `src/`: Directory for source code.
- `src/main.rs`: (For binary projects, default) Contains the `main` function.
- `src/lib.rs`: (For library projects, with `--lib`) Contains the library's public API.
- `.git/`: (If `--vcs git` or default) Git repository initialized.

The `cargo` package manager was developed alongside the Rust programming language from its early stages, aiming to provide a robust and integrated build system. Commands like `cargo init` and `cargo new` have been core functionalities from the beginning, simplifying project setup and adhering to best practices for Rust project structure. `cargo init` specifically addresses the need to initialize a project in an already existing directory, complementing `cargo new` which creates a new directory. Its evolution has focused on improving default settings (like the default Rust edition and VCS integration) and providing more flexibility through options, aligning with the language's stable releases and community needs.

cargo(1), cargo-new(1), cargo-build(1), cargo-run(1), cargo-check(1)