1CARGO-INSTALL(1) General Commands Manual CARGO-INSTALL(1)
2
6 cargo-install — Build and install a Rust binary
7
9 cargo install [options] crate[@version]…
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. By default only binaries, not examples, are
19 installed.
20 The installation root is determined, in order of precedence:
22 • --root option
24 • CARGO_INSTALL_ROOT environment variable
26 • install.root Cargo config value
28 <https://doc.rust-lang.org/cargo/reference/config.html>
29 • CARGO_HOME environment variable
31 • $HOME/.cargo
33 There are multiple sources from which a crate can be installed. The
35 default location is crates.io but the --git, --path, and --registry
36 flags can change this source. If the source contains more than one
37 package (such as crates.io or a git repository with multiple crates)
38 the crate argument is required to indicate which crate should be
39 installed.
40 Crates from crates.io can optionally specify the version they wish to
42 install via the --version flags, and similarly packages from git
43 repositories can optionally specify the branch, tag, or revision that
44 should be installed. If a crate has multiple binaries, the --bin
45 argument can selectively install only one of them, and if you’d rather
46 install examples the --example argument can be used as well.
47 If the package is already installed, Cargo will reinstall it if the
49 installed version does not appear to be up-to-date. If any of the
50 following values change, then Cargo will reinstall the package:
51 • The package version and source.
53 • The set of binary names installed.
55 • The chosen features.
57 • The profile (--profile).
59 • The target (--target).
61 Installing with --path will always build and install, unless there are
63 conflicting binaries from another package. The --force flag may be used
64 to force Cargo to always reinstall the package.
65 If the source is crates.io or --git then by default the crate will be
67 built in a temporary target directory. To avoid this, the target
68 directory can be specified by setting the CARGO_TARGET_DIR environment
69 variable to a relative path. In particular, this can be useful for
70 caching build artifacts on continuous integration systems.
71 Dealing with the Lockfile
73 By default, the Cargo.lock file that is included with the package will
74 be ignored. This means that Cargo will recompute which versions of
75 dependencies to use, possibly using newer versions that have been
76 released since the package was published. The --locked flag can be used
77 to force Cargo to use the packaged Cargo.lock file if it is available.
78 This may be useful for ensuring reproducible builds, to use the exact
79 same set of dependencies that were available when the package was
80 published. It may also be useful if a newer version of a dependency is
81 published that no longer builds on your system, or has other problems.
82 The downside to using --locked is that you will not receive any fixes
83 or updates to any dependency. Note that Cargo did not start publishing
84 Cargo.lock files until version 1.37, which means packages published
85 with prior versions will not have a Cargo.lock file available.
86 Configuration Discovery
88 This command operates on system or user level, not project level. This
89 means that the local configuration discovery
90 <https://doc.rust-lang.org/cargo/reference/config.html#hierarchical-structure>
91 is ignored. Instead, the configuration discovery begins at
92 $CARGO_HOME/config.toml. If the package is installed with --path $PATH,
93 the local configuration will be used, beginning discovery at
94 $PATH/.cargo/config.toml.
95
97 Install Options
98 --vers version, --version version
99 Specify a version to install. This may be a version requirement
100 <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.md>,
101 like ~1.2, to have Cargo select the newest version from the given
102 requirement. If the version does not have a requirement operator
103 (such as ^ or ~), then it must be in the form MAJOR.MINOR.PATCH,
104 and will install exactly that version; it is not treated as a caret
105 requirement like Cargo dependencies are.
106 --git url
108 Git URL to install the specified crate from.
109 --branch branch
111 Branch to use when installing from git.
112 --tag tag
114 Tag to use when installing from git.
115 --rev sha
117 Specific commit to use when installing from git.
118 --path path
120 Filesystem path to local crate to install.
121 --list
123 List all installed packages and their versions.
124 -f, --force
126 Force overwriting existing crates or binaries. This can be used if
127 a package has installed a binary with the same name as another
128 package. This is also useful if something has changed on the system
129 that you want to rebuild with, such as a newer version of rustc.
130 --no-track
132 By default, Cargo keeps track of the installed packages with a
133 metadata file stored in the installation root directory. This flag
134 tells Cargo not to use or create that file. With this flag, Cargo
135 will refuse to overwrite any existing files unless the --force flag
136 is used. This also disables Cargo’s ability to protect against
137 multiple concurrent invocations of Cargo installing at the same
138 time.
139 --bin name…
141 Install only the specified binary.
142 --bins
144 Install all binaries. This is the default behavior.
145 --example name…
147 Install only the specified example.
148 --examples
150 Install all examples.
151 --root dir
153 Directory to install packages into.
154 --registry registry
156 Name of the registry to use. Registry names are defined in Cargo
157 config files
158 <https://doc.rust-lang.org/cargo/reference/config.html>. If not
159 specified, the default registry is used, which is defined by the
160 registry.default config key which defaults to crates-io.
161 --index index
163 The URL of the registry index to use.
164 Feature Selection
166 The feature flags allow you to control which features are enabled. When
167 no feature options are given, the default feature is activated for
168 every selected package.
169 See the features documentation
171 <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
172 for more details.
173 -F features, --features features
175 Space or comma separated list of features to activate. Features of
176 workspace members may be enabled with package-name/feature-name
177 syntax. This flag may be specified multiple times, which enables
178 all specified features.
179 --all-features
181 Activate all available features of all selected packages.
182 --no-default-features
184 Do not activate the default feature of the selected packages.
185 Compilation Options
187 --target triple
188 Install for the given architecture. The default is the host
189 architecture. The general format of the triple is
190 <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
191 a list of supported targets.
192 This may also be specified with the build.target config value
194 <https://doc.rust-lang.org/cargo/reference/config.html>.
195 Note that specifying this flag makes Cargo run in a different mode
197 where the target artifacts are placed in a separate directory. See
198 the build cache
199 <https://doc.rust-lang.org/cargo/guide/build-cache.html>
200 documentation for more details.
201 --target-dir directory
203 Directory for all generated artifacts and intermediate files. May
204 also be specified with the CARGO_TARGET_DIR environment variable,
205 or the build.target-dir config value
206 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
207 to a new temporary folder located in the temporary directory of the
208 platform.
209 When using --path, by default it will use target directory in the
211 workspace of the local crate unless --target-dir is specified.
212 --debug
214 Build with the dev profile instead of the release profile. See also
215 the --profile option for choosing a specific profile by name.
216 --profile name
218 Install with the given profile. See the the reference
219 <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
220 details on profiles.
221 --ignore-rust-version
223 Install the target even if the selected Rust compiler is older than
224 the required Rust version as configured in the project’s
225 rust-version field.
226 --timings=fmts
228 Output information how long each compilation takes, and track
229 concurrency information over time. Accepts an optional
230 comma-separated list of output formats; --timings without an
231 argument will default to --timings=html. Specifying an output
232 format (rather than the default) is unstable and requires
233 -Zunstable-options. Valid output formats:
234 • html (unstable, requires -Zunstable-options): Write a
236 human-readable file cargo-timing.html to the
237 target/cargo-timings directory with a report of the
238 compilation. Also write a report to the same directory with a
239 timestamp in the filename if you want to look at older runs.
240 HTML output is suitable for human consumption only, and does
241 not provide machine-readable timing data.
242 • json (unstable, requires -Zunstable-options): Emit
244 machine-readable JSON information about timing information.
245 Manifest Options
247 --frozen, --locked
248 Either of these flags requires that the Cargo.lock file is
249 up-to-date. If the lock file is missing, or it needs to be updated,
250 Cargo will exit with an error. The --frozen flag also prevents
251 Cargo from attempting to access the network to determine if it is
252 out-of-date.
253 These may be used in environments where you want to assert that the
255 Cargo.lock file is up-to-date (such as a CI build) or want to avoid
256 network access.
257 --offline
259 Prevents Cargo from accessing the network for any reason. Without
260 this flag, Cargo will stop with an error if it needs to access the
261 network and the network is not available. With this flag, Cargo
262 will attempt to proceed without the network if possible.
263 Beware that this may result in different dependency resolution than
265 online mode. Cargo will restrict itself to crates that are
266 downloaded locally, even if there might be a newer version as
267 indicated in the local copy of the index. See the cargo-fetch(1)
268 command to download dependencies before going offline.
269 May also be specified with the net.offline config value
271 <https://doc.rust-lang.org/cargo/reference/config.html>.
272 Miscellaneous Options
274 -j N, --jobs N
275 Number of parallel jobs to run. May also be specified with the
276 build.jobs config value
277 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
278 to the number of logical CPUs. If negative, it sets the maximum
279 number of parallel jobs to the number of logical CPUs plus provided
280 value. If a string default is provided, it sets the value back to
281 defaults. Should not be 0.
282 --keep-going
284 Build as many crates in the dependency graph as possible, rather
285 than aborting the build on the first one that fails to build.
286 For example if the current package depends on dependencies fails
288 and works, one of which fails to build, cargo install -j1 may or
289 may not build the one that succeeds (depending on which one of the
290 two builds Cargo picked to run first), whereas cargo install -j1
291 --keep-going would definitely run both builds, even if the one run
292 first fails.
293 Display Options
295 -v, --verbose
296 Use verbose output. May be specified twice for “very verbose”
297 output which includes extra output such as dependency warnings and
298 build script output. May also be specified with the term.verbose
299 config value
300 <https://doc.rust-lang.org/cargo/reference/config.html>.
301 -q, --quiet
303 Do not print cargo log messages. May also be specified with the
304 term.quiet config value
305 <https://doc.rust-lang.org/cargo/reference/config.html>.
306 --color when
308 Control when colored output is used. Valid values:
309 • auto (default): Automatically detect if color support is
311 available on the terminal.
312 • always: Always display colors.
314 • never: Never display colors.
316 May also be specified with the term.color config value
318 <https://doc.rust-lang.org/cargo/reference/config.html>.
319 --message-format fmt
321 The output format for diagnostic messages. Can be specified
322 multiple times and consists of comma-separated values. Valid
323 values:
324 • human (default): Display in a human-readable text format.
326 Conflicts with short and json.
327 • short: Emit shorter, human-readable text messages. Conflicts
329 with human and json.
330 • json: Emit JSON messages to stdout. See the reference
332 <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
333 for more details. Conflicts with human and short.
334 • json-diagnostic-short: Ensure the rendered field of JSON
336 messages contains the “short” rendering from rustc. Cannot be
337 used with human or short.
338 • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
340 messages contains embedded ANSI color codes for respecting
341 rustc’s default color scheme. Cannot be used with human or
342 short.
343 • json-render-diagnostics: Instruct Cargo to not include rustc
345 diagnostics in JSON messages printed, but instead Cargo itself
346 should render the JSON diagnostics coming from rustc. Cargo’s
347 own JSON diagnostics and others coming from rustc are still
348 emitted. Cannot be used with human or short.
349 Common Options
351 +toolchain
352 If Cargo has been installed with rustup, and the first argument to
353 cargo begins with +, it will be interpreted as a rustup toolchain
354 name (such as +stable or +nightly). See the rustup documentation
355 <https://rust-lang.github.io/rustup/overrides.html> for more
356 information about how toolchain overrides work.
357 --config KEY=VALUE or PATH
359 Overrides a Cargo configuration value. The argument should be in
360 TOML syntax of KEY=VALUE, or provided as a path to an extra
361 configuration file. This flag may be specified multiple times. See
362 the command-line overrides section
363 <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
364 for more information.
365 -C PATH
367 Changes the current working directory before executing any
368 specified operations. This affects things like where cargo looks by
369 default for the project manifest (Cargo.toml), as well as the
370 directories searched for discovering .cargo/config.toml, for
371 example. This option must appear before the command name, for
372 example cargo -C path/to/my-project build.
373 This option is only available on the nightly channel
375 <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
376 requires the -Z unstable-options flag to enable (see #10098
377 <https://github.com/rust-lang/cargo/issues/10098>).
378 -h, --help
380 Prints help information.
381 -Z flag
383 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
384 details.
385
387 See the reference
388 <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
389 for details on environment variables that Cargo reads.
390
392 • 0: Cargo succeeded.
393 • 101: Cargo failed to complete.
395
397 1. Install or upgrade a package from crates.io:
398 cargo install ripgrep
400 2. Install or reinstall the package in the current directory:
402 cargo install --path .
404 3. View the list of installed packages:
406 cargo install --list
408
410 cargo(1), cargo-uninstall(1), cargo-search(1), cargo-publish(1)
411 CARGO-INSTALL(1)