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.
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 package is already installed, Cargo will reinstall it if the
48 installed version does not appear to be up-to-date. If any of the
49 following values change, then Cargo will reinstall the package:
50 • The package version and source.
52 • The set of binary names installed.
54 • The chosen features.
56 • The profile (--profile).
58 • The target (--target).
60 Installing with --path will always build and install, unless there are
62 conflicting binaries from another package. The --force flag may be used
63 to force Cargo to always reinstall the package.
64 If the source is crates.io or --git then by default the crate will be
66 built in a temporary target directory. To avoid this, the target
67 directory can be specified by setting the CARGO_TARGET_DIR environment
68 variable to a relative path. In particular, this can be useful for
69 caching build artifacts on continuous integration systems.
70 By default, the Cargo.lock file that is included with the package will
72 be ignored. This means that Cargo will recompute which versions of
73 dependencies to use, possibly using newer versions that have been
74 released since the package was published. The --locked flag can be used
75 to force Cargo to use the packaged Cargo.lock file if it is available.
76 This may be useful for ensuring reproducible builds, to use the exact
77 same set of dependencies that were available when the package was
78 published. It may also be useful if a newer version of a dependency is
79 published that no longer builds on your system, or has other problems.
80 The downside to using --locked is that you will not receive any fixes
81 or updates to any dependency. Note that Cargo did not start publishing
82 Cargo.lock files until version 1.37, which means packages published
83 with prior versions will not have a Cargo.lock file available.
84
86 Install Options
87 --vers version, --version version
88 Specify a version to install. This may be a version requirement
89 <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.md>,
90 like ~1.2, to have Cargo select the newest version from the given
91 requirement. If the version does not have a requirement operator
92 (such as ^ or ~), then it must be in the form MAJOR.MINOR.PATCH,
93 and will install exactly that version; it is not treated as a caret
94 requirement like Cargo dependencies are.
95 --git url
97 Git URL to install the specified crate from.
98 --branch branch
100 Branch to use when installing from git.
101 --tag tag
103 Tag to use when installing from git.
104 --rev sha
106 Specific commit to use when installing from git.
107 --path path
109 Filesystem path to local crate to install.
110 --list
112 List all installed packages and their versions.
113 -f, --force
115 Force overwriting existing crates or binaries. This can be used if
116 a package has installed a binary with the same name as another
117 package. This is also useful if something has changed on the system
118 that you want to rebuild with, such as a newer version of rustc.
119 --no-track
121 By default, Cargo keeps track of the installed packages with a
122 metadata file stored in the installation root directory. This flag
123 tells Cargo not to use or create that file. With this flag, Cargo
124 will refuse to overwrite any existing files unless the --force flag
125 is used. This also disables Cargo's ability to protect against
126 multiple concurrent invocations of Cargo installing at the same
127 time.
128 --bin name...
130 Install only the specified binary.
131 --bins
133 Install all binaries.
134 --example name...
136 Install only the specified example.
137 --examples
139 Install all examples.
140 --root dir
142 Directory to install packages into.
143 --registry registry
145 Name of the registry to use. Registry names are defined in Cargo
146 config files
147 <https://doc.rust-lang.org/cargo/reference/config.html>. If not
148 specified, the default registry is used, which is defined by the
149 registry.default config key which defaults to crates-io.
150 --index index
152 The URL of the registry index to use.
153 Feature Selection
155 The feature flags allow you to control which features are enabled. When
156 no feature options are given, the default feature is activated for
157 every selected package.
158 See the features documentation
160 <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
161 for more details.
162 -F features, --features features
164 Space or comma separated list of features to activate. Features of
165 workspace members may be enabled with package-name/feature-name
166 syntax. This flag may be specified multiple times, which enables
167 all specified features.
168 --all-features
170 Activate all available features of all selected packages.
171 --no-default-features
173 Do not activate the default feature of the selected packages.
174 Compilation Options
176 --target triple
177 Install for the given architecture. The default is the host
178 architecture. The general format of the triple is
179 <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
180 a list of supported targets.
181 This may also be specified with the build.target config value
183 <https://doc.rust-lang.org/cargo/reference/config.html>.
184 Note that specifying this flag makes Cargo run in a different mode
186 where the target artifacts are placed in a separate directory. See
187 the build cache
188 <https://doc.rust-lang.org/cargo/guide/build-cache.html>
189 documentation for more details.
190 --target-dir directory
192 Directory for all generated artifacts and intermediate files. May
193 also be specified with the CARGO_TARGET_DIR environment variable,
194 or the build.target-dir config value
195 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
196 to a new temporary folder located in the temporary directory of the
197 platform.
198 When using --path, by default it will use target directory in the
200 workspace of the local crate unless --target-dir is specified.
201 --debug
203 Build with the dev profile instead the release profile. See also
204 the --profile option for choosing a specific profile by name.
205 --profile name
207 Install with the given profile. See the the reference
208 <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
209 details on profiles.
210 --timings=fmts
212 Output information how long each compilation takes, and track
213 concurrency information over time. Accepts an optional
214 comma-separated list of output formats; --timings without an
215 argument will default to --timings=html. Specifying an output
216 format (rather than the default) is unstable and requires
217 -Zunstable-options. Valid output formats:
218 • html (unstable, requires -Zunstable-options): Write a
220 human-readable file cargo-timing.html to the
221 target/cargo-timings directory with a report of the
222 compilation. Also write a report to the same directory with a
223 timestamp in the filename if you want to look at older runs.
224 HTML output is suitable for human consumption only, and does
225 not provide machine-readable timing data.
226 • json (unstable, requires -Zunstable-options): Emit
228 machine-readable JSON information about timing information.
229 Manifest Options
231 --frozen, --locked
232 Either of these flags requires that the Cargo.lock file is
233 up-to-date. If the lock file is missing, or it needs to be updated,
234 Cargo will exit with an error. The --frozen flag also prevents
235 Cargo from attempting to access the network to determine if it is
236 out-of-date.
237 These may be used in environments where you want to assert that the
239 Cargo.lock file is up-to-date (such as a CI build) or want to avoid
240 network access.
241 --offline
243 Prevents Cargo from accessing the network for any reason. Without
244 this flag, Cargo will stop with an error if it needs to access the
245 network and the network is not available. With this flag, Cargo
246 will attempt to proceed without the network if possible.
247 Beware that this may result in different dependency resolution than
249 online mode. Cargo will restrict itself to crates that are
250 downloaded locally, even if there might be a newer version as
251 indicated in the local copy of the index. See the cargo-fetch(1)
252 command to download dependencies before going offline.
253 May also be specified with the net.offline config value
255 <https://doc.rust-lang.org/cargo/reference/config.html>.
256 Miscellaneous Options
258 -j N, --jobs N
259 Number of parallel jobs to run. May also be specified with the
260 build.jobs config value
261 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
262 to the number of logical CPUs. If negative, it sets the maximum
263 number of parallel jobs to the number of logical CPUs plus provided
264 value. Should not be 0.
265 --keep-going
267 Build as many crates in the dependency graph as possible, rather
268 than aborting the build on the first one that fails to build.
269 Unstable, requires -Zunstable-options.
270 Display Options
272 -v, --verbose
273 Use verbose output. May be specified twice for "very verbose"
274 output which includes extra output such as dependency warnings and
275 build script output. May also be specified with the term.verbose
276 config value
277 <https://doc.rust-lang.org/cargo/reference/config.html>.
278 -q, --quiet
280 Do not print cargo log messages. May also be specified with the
281 term.quiet config value
282 <https://doc.rust-lang.org/cargo/reference/config.html>.
283 --color when
285 Control when colored output is used. Valid values:
286 • auto (default): Automatically detect if color support is
288 available on the terminal.
289 • always: Always display colors.
291 • never: Never display colors.
293 May also be specified with the term.color config value
295 <https://doc.rust-lang.org/cargo/reference/config.html>.
296 --message-format fmt
298 The output format for diagnostic messages. Can be specified
299 multiple times and consists of comma-separated values. Valid
300 values:
301 • human (default): Display in a human-readable text format.
303 Conflicts with short and json.
304 • short: Emit shorter, human-readable text messages. Conflicts
306 with human and json.
307 • json: Emit JSON messages to stdout. See the reference
309 <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
310 for more details. Conflicts with human and short.
311 • json-diagnostic-short: Ensure the rendered field of JSON
313 messages contains the "short" rendering from rustc. Cannot be
314 used with human or short.
315 • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
317 messages contains embedded ANSI color codes for respecting
318 rustc's default color scheme. Cannot be used with human or
319 short.
320 • json-render-diagnostics: Instruct Cargo to not include rustc
322 diagnostics in JSON messages printed, but instead Cargo itself
323 should render the JSON diagnostics coming from rustc. Cargo's
324 own JSON diagnostics and others coming from rustc are still
325 emitted. Cannot be used with human or short.
326 Common Options
328 +toolchain
329 If Cargo has been installed with rustup, and the first argument to
330 cargo begins with +, it will be interpreted as a rustup toolchain
331 name (such as +stable or +nightly). See the rustup documentation
332 <https://rust-lang.github.io/rustup/overrides.html> for more
333 information about how toolchain overrides work.
334 --config KEY=VALUE or PATH
336 Overrides a Cargo configuration value. The argument should be in
337 TOML syntax of KEY=VALUE, or provided as a path to an extra
338 configuration file. This flag may be specified multiple times. See
339 the command-line overrides section
340 <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
341 for more information.
342 -h, --help
344 Prints help information.
345 -Z flag
347 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
348 details.
349
351 See the reference
352 <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
353 for details on environment variables that Cargo reads.
354
356 • 0: Cargo succeeded.
357 • 101: Cargo failed to complete.
359
361 1. Install or upgrade a package from crates.io:
362 cargo install ripgrep
364 2. Install or reinstall the package in the current directory:
366 cargo install --path .
368 3. View the list of installed packages:
370 cargo install --list
372
374 cargo(1), cargo-uninstall(1), cargo-search(1), cargo-publish(1)
375 CARGO-INSTALL(1)