1CARGO-INSTALL(1) CARGO-INSTALL(1)
2
6 cargo-install - Build and install a Rust binary
7
9 cargo install [OPTIONS] CRATE...
10 cargo install [OPTIONS] --path PATH
11 cargo install [OPTIONS] --git URL [CRATE...]
12 cargo install [OPTIONS] --list
13
15 This command manages Cargo’s local set of installed binary crates. Only
16 packages which have executable [[bin]] or [[example]] targets can be
17 installed, and all executables are installed into the installation
18 root’s bin folder.
19 The installation root is determined, in order of precedence:
21 · --root option
23 · CARGO_INSTALL_ROOT environment variable
25 · install.root Cargo config value
27 <https://doc.rust-lang.org/cargo/reference/config.html>
28 · CARGO_HOME environment variable
30 · $HOME/.cargo
32 There are multiple sources from which a crate can be installed. The
34 default location is crates.io but the --git, --path, and --registry
35 flags can change this source. If the source contains more than one
36 package (such as crates.io or a git repository with multiple crates)
37 the CRATE argument is required to indicate which crate should be
38 installed.
39 Crates from crates.io can optionally specify the version they wish to
41 install via the --version flags, and similarly packages from git
42 repositories can optionally specify the branch, tag, or revision that
43 should be installed. If a crate has multiple binaries, the --bin
44 argument can selectively install only one of them, and if you’d rather
45 install examples the --example argument can be used as well.
46 If the source is crates.io or --git then by default the crate will be
48 built in a temporary target directory. To avoid this, the target
49 directory can be specified by setting the CARGO_TARGET_DIR environment
50 variable to a relative path. In particular, this can be useful for
51 caching build artifacts on continuous integration systems.
52 By default, the Cargo.lock file that is included with the package will
54 be ignored. This means that Cargo will recompute which versions of
55 dependencies to use, possibly using newer versions that have been
56 released since the package was published. The --locked flag can be used
57 to force Cargo to use the packaged Cargo.lock file if it is available.
58 This may be useful for ensuring reproducible builds, to use the exact
59 same set of dependencies that were available when the package was
60 published. It may also be useful if a newer version of a dependency is
61 published that no longer builds on your system, or has other problems.
62 The downside to using --locked is that you will not receive any fixes
63 or updates to any dependency. Note that Cargo did not start publishing
64 Cargo.lock files until version 1.37, which means packages published
65 with prior versions will not have a Cargo.lock file available.
66
68 Install Options
69 --vers VERSION, --version VERSION
70 Specify a version to install.
71 --git URL
73 Git URL to install the specified crate from.
74 --branch BRANCH
76 Branch to use when installing from git.
77 --tag TAG
79 Tag to use when installing from git.
80 --rev SHA
82 Specific commit to use when installing from git.
83 --path PATH
85 Filesystem path to local crate to install.
86 --list
88 List all installed packages and their versions.
89 -f, --force
91 Force overwriting existing crates or binaries. This can be used to
92 reinstall or upgrade a crate.
93 --bin NAME...
95 Install only the specified binary.
96 --bins
98 Install all binaries.
99 --example NAME...
101 Install only the specified example.
102 --examples
104 Install all examples.
105 --root DIR
107 Directory to install packages into.
108 --registry REGISTRY
110 Name of the registry to use. Registry names are defined in Cargo
111 config files
112 <https://doc.rust-lang.org/cargo/reference/config.html>. If not
113 specified, the default registry is used, which is defined by the
114 registry.default config key which defaults to crates-io.
115 Feature Selection
117 When no feature options are given, the default feature is activated for
118 every selected package.
119 --features FEATURES
121 Space or comma separated list of features to activate. These
122 features only apply to the current directory’s package. Features of
123 direct dependencies may be enabled with <dep-name>/<feature-name>
124 syntax.
125 --all-features
127 Activate all available features of all selected packages.
128 --no-default-features
130 Do not activate the default feature of the current directory’s
131 package.
132 Compilation Options
134 --target TRIPLE
135 Install for the given architecture. The default is the host
136 architecture. The general format of the triple is
137 <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
138 a list of supported targets.
139 This may also be specified with the build.target config value
141 <https://doc.rust-lang.org/cargo/reference/config.html>.
142 --debug
144 Build with the dev profile instead the release profile.
145 Manifest Options
147 --frozen, --locked
148 Either of these flags requires that the Cargo.lock file is
149 up-to-date. If the lock file is missing, or it needs to be updated,
150 Cargo will exit with an error. The --frozen flag also prevents
151 Cargo from attempting to access the network to determine if it is
152 out-of-date.
153 These may be used in environments where you want to assert that the
155 Cargo.lock file is up-to-date (such as a CI build) or want to avoid
156 network access.
157 --offline
159 Prevents Cargo from accessing the network for any reason. Without
160 this flag, Cargo will stop with an error if it needs to access the
161 network and the network is not available. With this flag, Cargo
162 will attempt to proceed without the network if possible.
163 Beware that this may result in different dependency resolution than
165 online mode. Cargo will restrict itself to crates that are
166 downloaded locally, even if there might be a newer version as
167 indicated in the local copy of the index. See the cargo-fetch(1)
168 command to download dependencies before going offline.
169 May also be specified with the net.offline config value
171 <https://doc.rust-lang.org/cargo/reference/config.html>.
172 Miscellaneous Options
174 -j N, --jobs N
175 Number of parallel jobs to run. May also be specified with the
176 build.jobs config value
177 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
178 to the number of CPUs.
179 Display Options
181 -v, --verbose
182 Use verbose output. May be specified twice for "very verbose"
183 output which includes extra output such as dependency warnings and
184 build script output. May also be specified with the term.verbose
185 config value
186 <https://doc.rust-lang.org/cargo/reference/config.html>.
187 -q, --quiet
189 No output printed to stdout.
190 --color WHEN
192 Control when colored output is used. Valid values:
193 · auto (default): Automatically detect if color support is
195 available on the terminal.
196 · always: Always display colors.
198 · never: Never display colors.
200 May also be specified with the term.color config value
202 <https://doc.rust-lang.org/cargo/reference/config.html>.
203 Common Options
205 -h, --help
206 Prints help information.
207 -Z FLAG...
209 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
210 details.
211
213 See the reference
214 <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
215 for details on environment variables that Cargo reads.
216
218 0
219 Cargo succeeded.
220 101
222 Cargo failed to complete.
223
225 1. Install a package from crates.io:
226 cargo install ripgrep
228 2. Reinstall or upgrade a package:
230 cargo install ripgrep --force
232
234 cargo(1), cargo-uninstall(1), cargo-search(1), cargo-publish(1)
235 2019-07-15 CARGO-INSTALL(1)