---
name: "cargo-new"
section: "1"
platform: "linux"
package: "rust"
version: "1:1.99.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/cargo-new"
---

# cargo-new(1)

Create a new Cargo package

## NAME

cargo-new — Create a new Cargo package

## SYNOPSIS

**cargo new** \[*options*\] *path*

## DESCRIPTION

This command will create a new Cargo package in the given directory. This includes a simple template with a **Cargo.toml** manifest, sample source file, and a VCS ignore file. If the directory is not already in a VCS repository, then a new repository is created (see **--vcs** below).

See [**cargo-init**(1)](/cargo-init/1.md) for a similar command which will create a new manifest in an existing directory.

## OPTIONS

### New 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 2024. Possible values: 2015, 2018, 2021, 2024

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

  This sets the **publish** field in **Cargo.toml** to the given registry name which will restrict publishing only to that registry.

  Registry names are defined in *Cargo config files* \<https://doc.rust-lang.org/cargo/reference/config.html\>. If not specified, the default registry defined by the **registry.default** config key is used. If the default registry is not set and **--registry** is not used, the **publish** field will not be set which means that publishing will not be restricted.

### 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* \<https://doc.rust-lang.org/cargo/reference/config.html\>.

- **-q**, **--quiet**

  Do not print cargo log messages. May also be specified with the **term.quiet** *config value* \<https://doc.rust-lang.org/cargo/reference/config.html\>.

- **--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* \<https://doc.rust-lang.org/cargo/reference/config.html\>.

### Common Options

**+***toolchain*

If Cargo has been installed with rustup, and the first argument to **cargo** begins with **+**, it will be interpreted as a rustup toolchain name (such as **+stable** or **+nightly**). See the *rustup documentation* \<https://rust-lang.github.io/rustup/overrides.html\> for more information about how toolchain overrides work.

**--config** *KEY=VALUE* or *PATH*

Overrides a Cargo configuration value. The argument should be in TOML syntax of **KEY=VALUE**, or provided as a path to an extra configuration file. This flag may be specified multiple times. See the *command-line overrides section* \<https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides\> for more information.

- **-C** *PATH*

  Changes the current working directory before executing any specified operations. This affects things like where cargo looks by default for the project manifest (**Cargo.toml**), as well as the directories searched for discovering **.cargo/config.toml**, for example. This option must appear before the command name, for example **cargo -C path/to/my-project build**.

  This option is only available on the *nightly* *channel* \<https://doc.rust-lang.org/book/appendix-07-nightly-rust.html\> and requires the **-Z unstable-options** flag to enable (see *#10098* \<https://github.com/rust-lang/cargo/issues/10098\>).

- **-h**, **--help**

  Prints help information.

- **-Z** *flag*

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

## ENVIRONMENT

See *the reference* \<https://doc.rust-lang.org/cargo/reference/environment-variables.html\> 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 given directory:

```
cargo new foo
```

## SEE ALSO

[**cargo**(1)](/cargo/1.md), [**cargo-init**(1)](/cargo-init/1.md)