= cargo-install(1)
:idprefix: cargo_install_
:doctype: manpage
:actionverb: Install

== NAME

cargo-install - Build and install a Rust binary

== SYNOPSIS

[%hardbreaks]
`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.

include::description-install-root.adoc[]

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.

include::options-registry.adoc[]

include::options-features.adoc[]

=== Compilation Options

include::options-target-triple.adoc[]

*--debug*::
    Build with the `dev` profile instead the `release` profile.

=== Miscellaneous Options

include::options-jobs.adoc[]

=== Display Options

include::options-display.adoc[]

=== Common Options

include::options-common.adoc[]

include::section-environment.adoc[]

include::section-exit-status.adoc[]

== EXAMPLES

. Install a package from crates.io:

    cargo install ripgrep

. Reinstall or upgrade a package:

    cargo install ripgrep --force

== SEE ALSO
man:cargo[1], man:cargo-uninstall[1], man:cargo-search[1], man:cargo-publish[1]
