# cargo init

## NAME

cargo-init - Create a new Cargo package in an existing directory

## SYNOPSIS

`cargo init [OPTIONS] [PATH]`

## DESCRIPTION

This command will create a new Cargo manifest in the current directory. Give a path as an argument to create in the given directory.

If there are typically-named Rust source files already in the directory, those will be used. If not, then a sample `src/main.rs` file will be created, or `src/lib.rs` if `--lib` is passed.

If the directory is not already in a VCS repository, then a new repository is created (see `--vcs` below).

The "authors" field in the manifest is determined from the environment or configuration settings. A name is required and is determined from (first match wins):

- `cargo-new.name` Cargo config value

- `CARGO_NAME` environment variable

- `GIT_AUTHOR_NAME` environment variable

- `GIT_COMMITTER_NAME` environment variable

- `user.name` git configuration value

- `USER` environment variable

- `USERNAME` environment variable

- `NAME` environment variable

The email address is optional and is determined from:

- `cargo-new.email` Cargo config value

- `CARGO_EMAIL` environment variable

- `GIT_AUTHOR_EMAIL` environment variable

- `GIT_COMMITTER_EMAIL` environment variable

- `user.email` git configuration value

- `EMAIL` environment variable

See the reference for more information about configuration files.

See cargo-new(1) for a similar command which will create a new package in a new directory.

## OPTIONS

### Init Options

--bin

  Create a package with a binary target (`src/main.rs`). This is the default behavior.

--lib

  Create a package with a library target (`src/lib.rs`).

--edition EDITION

  Specify the Rust edition to use. Default is 2018. Possible values: 2015, 2018

--name NAME

  Set the package name. Defaults to the directory name.

--vcs VCS

  Initialize a new VCS repository for the given version control system (git, hg, pijul, or fossil) or do not initialize any version control at all (none). If not specified, defaults to `git` or the configuration value `cargo-new.vcs`, or `none` if already inside a VCS repository.

--registry REGISTRY

  Alternative registry to use. This sets the `publish` field which will restrict publishing only to the given registry name.

  This option is unstable and available only on the nightly channel and requires the `-Z unstable-options` flag to enable.

### Display Options

-v
--verbose

  Use verbose output. May be specified twice for "very verbose" output which includes extra output such as dependency warnings and build script output. May also be specified with the `term.verbose` config value.

-q
--quiet

  No output printed to stdout.

--color WHEN

  Control when colored output is used. Valid values:

  - `auto` (default): Automatically detect if color support is available on the terminal.

  - `always`: Always display colors.

  - `never`: Never display colors.

  May also be specified with the `term.color` config value.

### Common Options

-h
--help

  Prints help information.

-Z FLAG…​

  Unstable (nightly-only) flags to Cargo. Run `cargo -Z help` for details.

## ENVIRONMENT

See the reference for details on environment variables that Cargo reads.

## Exit Status

0

  Cargo succeeded.

101

  Cargo failed to complete.

## EXAMPLES

1. Create a binary Cargo package in the current directory:

       cargo init

## SEE ALSO

cargo(1), cargo-new(1)