# cargo install

## NAME

cargo-install - Build and install a Rust binary

## SYNOPSIS

`cargo install [OPTIONS] CRATE…​`
`cargo install [OPTIONS] --path PATH`
`cargo install [OPTIONS] --git URL [CRATE…​]`
`cargo install [OPTIONS] --list`

## DESCRIPTION

This command manages Cargo’s local set of installed binary crates. Only packages which have `[[bin]]` targets can be installed, and all binaries are installed into the installation root’s `bin` folder.

The installation root is determined, in order of precedence:

- `--root` option

- `CARGO_INSTALL_ROOT` environment variable

- `install.root` Cargo config value

- `CARGO_HOME` environment variable

- `$HOME/.cargo`

There are multiple sources from which a crate can be installed. The default location is crates.io but the `--git` and `--path` flags can change this source. If the source contains more than one package (such as crates.io or a git repository with multiple crates) the CRATE argument is required to indicate which crate should be installed.

Crates from crates.io can optionally specify the version they wish to install via the `--version` flags, and similarly packages from git repositories can optionally specify the branch, tag, or revision that should be installed. If a crate has multiple binaries, the `--bin` argument can selectively install only one of them, and if you’d rather install examples the `--example` argument can be used as well.

If the source is crates.io or `--git` then by default the crate will be built in a temporary target directory. To avoid this, the target directory can be specified by setting the `CARGO_TARGET_DIR` environment variable to a relative path. In particular, this can be useful for caching build artifacts on continuous integration systems.

## OPTIONS

### Install Options

--vers VERSION
--version VERSION

  Specify a version to install from crates.io.

--git URL

  Git URL to install the specified crate from.

--branch BRANCH

  Branch to use when installing from git.

--tag TAG

  Tag to use when installing from git.

--rev SHA

  Specific commit to use when installing from git.

--path PATH

  Filesystem path to local crate to install.

--list

  List all installed packages and their versions.

-f
--force

  Force overwriting existing crates or binaries. This can be used to reinstall or upgrade a crate.

--bin NAME…​

  Install only the specified binary.

--bins

  Install all binaries.

--example NAME…​

  Install only the specified example.

--examples

  Install all examples.

--root DIR

  Directory to install packages into.

--registry REGISTRY

  Alternative registry to use.

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

### Feature Selection

When no feature options are given, the `default` feature is activated for every selected package.

--features FEATURES

  Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies may be enabled with `<dep-name>/<feature-name>` syntax.

--all-features

  Activate all available features of all selected packages.

--no-default-features

  Do not activate the `default` feature of the current directory’s package.

### Compilation Options

--target TRIPLE

  Install for the given architecture. The default is the host architecture. The general format of the triple is `<arch><sub>-<vendor>-<sys>-<abi>`. Run `rustc --print target-list` for a list of supported targets.

  This may also be specified with the `build.target` config value.

--debug

  Build with the `dev` profile instead the `release` profile.

### Miscellaneous Options

-j N
--jobs N

  Number of parallel jobs to run. May also be specified with the `build.jobs` config value. Defaults to the number of CPUs.

### 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. Install a package from crates.io:

       cargo install ripgrep

2. Reinstall or upgrade a package:

       cargo install ripgrep --force

## SEE ALSO

cargo(1), cargo-uninstall(1), cargo-search(1), cargo-publish(1)