1## Environment Variables
2
3Cargo sets and reads a number of environment variables which your code can detect
4or override. Here is a list of the variables Cargo sets, organized by when it interacts
5with them:
6
7### Environment variables Cargo reads
8
9You can override these environment variables to change Cargo's behavior on your
10system:
11
12* `CARGO_HOME` — Cargo maintains a local cache of the registry index and of
13  git checkouts of crates. By default these are stored under `$HOME/.cargo`
14  (`%USERPROFILE%\.cargo` on Windows), but this variable overrides the
15  location of this directory. Once a crate is cached it is not removed by the
16  clean command.
17  For more details refer to the [guide](../guide/cargo-home.md).
18* `CARGO_TARGET_DIR` — Location of where to place all generated artifacts,
19  relative to the current working directory. See [`build.target-dir`] to set
20  via config.
21* `RUSTC` — Instead of running `rustc`, Cargo will execute this specified
22  compiler instead. See [`build.rustc`] to set via config.
23* `RUSTC_WRAPPER` — Instead of simply running `rustc`, Cargo will execute this
24  specified wrapper instead, passing as its command-line arguments the rustc
25  invocation, with the first argument being `rustc`. Useful to set up a build
26  cache tool such as `sccache`. See [`build.rustc-wrapper`] to set via config.
27* `RUSTC_WORKSPACE_WRAPPER` — Instead of simply running `rustc`, Cargo will
28  execute this specified wrapper instead for workspace members only, passing
29  as its command-line arguments the rustc invocation, with the first argument
30  being `rustc`. It affects the filename hash so that artifacts produced by
31  the wrapper are cached separately. See [`build.rustc-workspace-wrapper`]
32  to set via config.
33* `RUSTDOC` — Instead of running `rustdoc`, Cargo will execute this specified
34  `rustdoc` instance instead. See [`build.rustdoc`] to set via config.
35* `RUSTDOCFLAGS` — A space-separated list of custom flags to pass to all `rustdoc`
36  invocations that Cargo performs. In contrast with [`cargo rustdoc`], this is
37  useful for passing a flag to *all* `rustdoc` instances. See
38  [`build.rustdocflags`] for some more ways to set flags. This string is
39  split by whitespace; for a more robust encoding of multiple arguments,
40  set `CARGO_ENCODED_RUSTDOCFLAGS` instead with arguments separated by
41  `0x1f` (ASCII Unit Separator).
42* `RUSTFLAGS` — A space-separated list of custom flags to pass to all compiler
43  invocations that Cargo performs. In contrast with [`cargo rustc`], this is
44  useful for passing a flag to *all* compiler instances. See
45  [`build.rustflags`] for some more ways to set flags. This string is
46  split by whitespace; for a more robust encoding of multiple arguments,
47  set `CARGO_ENCODED_RUSTFLAGS` instead with arguments separated by
48  `0x1f` (ASCII Unit Separator).
49* `CARGO_INCREMENTAL` — If this is set to 1 then Cargo will force [incremental
50  compilation] to be enabled for the current compilation, and when set to 0 it
51  will force disabling it. If this env var isn't present then cargo's defaults
52  will otherwise be used. See also [`build.incremental`] config value.
53* `CARGO_CACHE_RUSTC_INFO` — If this is set to 0 then Cargo will not try to cache
54  compiler version information.
55* `HTTPS_PROXY` or `https_proxy` or `http_proxy` — The HTTP proxy to use, see
56  [`http.proxy`] for more detail.
57* `HTTP_TIMEOUT` — The HTTP timeout in seconds, see [`http.timeout`] for more
58  detail.
59* `TERM` — If this is set to `dumb`, it disables the progress bar.
60* `BROWSER` — The web browser to execute to open documentation with [`cargo
61  doc`]'s' `--open` flag, see [`doc.browser`] for more details.
62* `RUSTFMT` — Instead of running `rustfmt`,
63  [`cargo fmt`](https://github.com/rust-lang/rustfmt) will execute this specified
64  `rustfmt` instance instead.
65
66#### Configuration environment variables
67
68Cargo reads environment variables for configuration values. See the
69[configuration chapter][config-env] for more details. In summary, the
70supported environment variables are:
71
72* `CARGO_ALIAS_<name>` — Command aliases, see [`alias`].
73* `CARGO_BUILD_JOBS` — Number of parallel jobs, see [`build.jobs`].
74* `CARGO_BUILD_RUSTC` — The `rustc` executable, see [`build.rustc`].
75* `CARGO_BUILD_RUSTC_WRAPPER` — The `rustc` wrapper, see [`build.rustc-wrapper`].
76* `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER` — The `rustc` wrapper for workspace members only, see [`build.rustc-workspace-wrapper`].
77* `CARGO_BUILD_RUSTDOC` — The `rustdoc` executable, see [`build.rustdoc`].
78* `CARGO_BUILD_TARGET` — The default target platform, see [`build.target`].
79* `CARGO_BUILD_TARGET_DIR` — The default output directory, see [`build.target-dir`].
80* `CARGO_BUILD_RUSTFLAGS` — Extra `rustc` flags, see [`build.rustflags`].
81* `CARGO_BUILD_RUSTDOCFLAGS` — Extra `rustdoc` flags, see [`build.rustdocflags`].
82* `CARGO_BUILD_INCREMENTAL` — Incremental compilation, see [`build.incremental`].
83* `CARGO_BUILD_DEP_INFO_BASEDIR` — Dep-info relative directory, see [`build.dep-info-basedir`].
84* `CARGO_BUILD_PIPELINING` — Whether or not to use `rustc` pipelining, see [`build.pipelining`].
85* `CARGO_CARGO_NEW_VCS` — The default source control system with [`cargo new`], see [`cargo-new.vcs`].
86* `CARGO_HTTP_DEBUG` — Enables HTTP debugging, see [`http.debug`].
87* `CARGO_HTTP_PROXY` — Enables HTTP proxy, see [`http.proxy`].
88* `CARGO_HTTP_TIMEOUT` — The HTTP timeout, see [`http.timeout`].
89* `CARGO_HTTP_CAINFO` — The TLS certificate Certificate Authority file, see [`http.cainfo`].
90* `CARGO_HTTP_CHECK_REVOKE` — Disables TLS certificate revocation checks, see [`http.check-revoke`].
91* `CARGO_HTTP_SSL_VERSION` — The TLS version to use, see [`http.ssl-version`].
92* `CARGO_HTTP_LOW_SPEED_LIMIT` — The HTTP low-speed limit, see [`http.low-speed-limit`].
93* `CARGO_HTTP_MULTIPLEXING` — Whether HTTP/2 multiplexing is used, see [`http.multiplexing`].
94* `CARGO_HTTP_USER_AGENT` — The HTTP user-agent header, see [`http.user-agent`].
95* `CARGO_INSTALL_ROOT` — The default directory for [`cargo install`], see [`install.root`].
96* `CARGO_NET_RETRY` — Number of times to retry network errors, see [`net.retry`].
97* `CARGO_NET_GIT_FETCH_WITH_CLI` — Enables the use of the `git` executable to fetch, see [`net.git-fetch-with-cli`].
98* `CARGO_NET_OFFLINE` — Offline mode, see [`net.offline`].
99* `CARGO_PROFILE_<name>_BUILD_OVERRIDE_<key>` — Override build script profile, see [`profile.<name>.build-override`].
100* `CARGO_PROFILE_<name>_CODEGEN_UNITS` — Set code generation units, see [`profile.<name>.codegen-units`].
101* `CARGO_PROFILE_<name>_DEBUG` — What kind of debug info to include, see [`profile.<name>.debug`].
102* `CARGO_PROFILE_<name>_DEBUG_ASSERTIONS` — Enable/disable debug assertions, see [`profile.<name>.debug-assertions`].
103* `CARGO_PROFILE_<name>_INCREMENTAL` — Enable/disable incremental compilation, see [`profile.<name>.incremental`].
104* `CARGO_PROFILE_<name>_LTO` — Link-time optimization, see [`profile.<name>.lto`].
105* `CARGO_PROFILE_<name>_OVERFLOW_CHECKS` — Enable/disable overflow checks, see [`profile.<name>.overflow-checks`].
106* `CARGO_PROFILE_<name>_OPT_LEVEL` — Set the optimization level, see [`profile.<name>.opt-level`].
107* `CARGO_PROFILE_<name>_PANIC` — The panic strategy to use, see [`profile.<name>.panic`].
108* `CARGO_PROFILE_<name>_RPATH` — The rpath linking option, see [`profile.<name>.rpath`].
109* `CARGO_PROFILE_<name>_SPLIT_DEBUGINFO` — Controls debug file output behavior, see [`profile.<name>.split-debuginfo`].
110* `CARGO_REGISTRIES_<name>_INDEX` — URL of a registry index, see [`registries.<name>.index`].
111* `CARGO_REGISTRIES_<name>_TOKEN` — Authentication token of a registry, see [`registries.<name>.token`].
112* `CARGO_REGISTRY_DEFAULT` — Default registry for the `--registry` flag, see [`registry.default`].
113* `CARGO_REGISTRY_TOKEN` — Authentication token for [crates.io], see [`registry.token`].
114* `CARGO_TARGET_<triple>_LINKER` — The linker to use, see [`target.<triple>.linker`]. The triple must be [converted to uppercase and underscores](config.md#environment-variables).
115* `CARGO_TARGET_<triple>_RUNNER` — The executable runner, see [`target.<triple>.runner`].
116* `CARGO_TARGET_<triple>_RUSTFLAGS` — Extra `rustc` flags for a target, see [`target.<triple>.rustflags`].
117* `CARGO_TERM_VERBOSE` — The default terminal verbosity, see [`term.verbose`].
118* `CARGO_TERM_COLOR` — The default color mode, see [`term.color`].
119* `CARGO_TERM_PROGRESS_WHEN` — The default progress bar showing mode, see [`term.progress.when`].
120* `CARGO_TERM_PROGRESS_WIDTH` — The default progress bar width, see [`term.progress.width`].
121
122[`cargo doc`]: ../commands/cargo-doc.md
123[`cargo install`]: ../commands/cargo-install.md
124[`cargo new`]: ../commands/cargo-new.md
125[`cargo rustc`]: ../commands/cargo-rustc.md
126[`cargo rustdoc`]: ../commands/cargo-rustdoc.md
127[config-env]: config.md#environment-variables
128[crates.io]: https://crates.io/
129[incremental compilation]: profiles.md#incremental
130[`alias`]: config.md#alias
131[`build.jobs`]: config.md#buildjobs
132[`build.rustc`]: config.md#buildrustc
133[`build.rustc-wrapper`]: config.md#buildrustc-wrapper
134[`build.rustc-workspace-wrapper`]: config.md#buildrustc-workspace-wrapper
135[`build.rustdoc`]: config.md#buildrustdoc
136[`build.target`]: config.md#buildtarget
137[`build.target-dir`]: config.md#buildtarget-dir
138[`build.rustflags`]: config.md#buildrustflags
139[`build.rustdocflags`]: config.md#buildrustdocflags
140[`build.incremental`]: config.md#buildincremental
141[`build.dep-info-basedir`]: config.md#builddep-info-basedir
142[`build.pipelining`]: config.md#buildpipelining
143[`doc.browser`]: config.md#docbrowser
144[`cargo-new.name`]: config.md#cargo-newname
145[`cargo-new.email`]: config.md#cargo-newemail
146[`cargo-new.vcs`]: config.md#cargo-newvcs
147[`http.debug`]: config.md#httpdebug
148[`http.proxy`]: config.md#httpproxy
149[`http.timeout`]: config.md#httptimeout
150[`http.cainfo`]: config.md#httpcainfo
151[`http.check-revoke`]: config.md#httpcheck-revoke
152[`http.ssl-version`]: config.md#httpssl-version
153[`http.low-speed-limit`]: config.md#httplow-speed-limit
154[`http.multiplexing`]: config.md#httpmultiplexing
155[`http.user-agent`]: config.md#httpuser-agent
156[`install.root`]: config.md#installroot
157[`net.retry`]: config.md#netretry
158[`net.git-fetch-with-cli`]: config.md#netgit-fetch-with-cli
159[`net.offline`]: config.md#netoffline
160[`profile.<name>.build-override`]: config.md#profilenamebuild-override
161[`profile.<name>.codegen-units`]: config.md#profilenamecodegen-units
162[`profile.<name>.debug`]: config.md#profilenamedebug
163[`profile.<name>.debug-assertions`]: config.md#profilenamedebug-assertions
164[`profile.<name>.incremental`]: config.md#profilenameincremental
165[`profile.<name>.lto`]: config.md#profilenamelto
166[`profile.<name>.overflow-checks`]: config.md#profilenameoverflow-checks
167[`profile.<name>.opt-level`]: config.md#profilenameopt-level
168[`profile.<name>.panic`]: config.md#profilenamepanic
169[`profile.<name>.rpath`]: config.md#profilenamerpath
170[`profile.<name>.split-debuginfo`]: config.md#profilenamesplit-debuginfo
171[`registries.<name>.index`]: config.md#registriesnameindex
172[`registries.<name>.token`]: config.md#registriesnametoken
173[`registry.default`]: config.md#registrydefault
174[`registry.token`]: config.md#registrytoken
175[`target.<triple>.linker`]: config.md#targettriplelinker
176[`target.<triple>.runner`]: config.md#targettriplerunner
177[`target.<triple>.rustflags`]: config.md#targettriplerustflags
178[`term.verbose`]: config.md#termverbose
179[`term.color`]: config.md#termcolor
180[`term.progress.when`]: config.md#termprogresswhen
181[`term.progress.width`]: config.md#termprogresswidth
182
183### Environment variables Cargo sets for crates
184
185Cargo exposes these environment variables to your crate when it is compiled.
186Note that this applies for running binaries with `cargo run` and `cargo test`
187as well. To get the value of any of these variables in a Rust program, do
188this:
189
190```rust,ignore
191let version = env!("CARGO_PKG_VERSION");
192```
193
194`version` will now contain the value of `CARGO_PKG_VERSION`.
195
196Note that if one of these values is not provided in the manifest, the
197corresponding environment variable is set to the empty string, `""`.
198
199* `CARGO` — Path to the `cargo` binary performing the build.
200* `CARGO_MANIFEST_DIR` — The directory containing the manifest of your package.
201* `CARGO_PKG_VERSION` — The full version of your package.
202* `CARGO_PKG_VERSION_MAJOR` — The major version of your package.
203* `CARGO_PKG_VERSION_MINOR` — The minor version of your package.
204* `CARGO_PKG_VERSION_PATCH` — The patch version of your package.
205* `CARGO_PKG_VERSION_PRE` — The pre-release version of your package.
206* `CARGO_PKG_AUTHORS` — Colon separated list of authors from the manifest of your package.
207* `CARGO_PKG_NAME` — The name of your package.
208* `CARGO_PKG_DESCRIPTION` — The description from the manifest of your package.
209* `CARGO_PKG_HOMEPAGE` — The home page from the manifest of your package.
210* `CARGO_PKG_REPOSITORY` — The repository from the manifest of your package.
211* `CARGO_PKG_LICENSE` — The license from the manifest of your package.
212* `CARGO_PKG_LICENSE_FILE` — The license file from the manifest of your package.
213* `CARGO_CRATE_NAME` — The name of the crate that is currently being compiled.
214* `CARGO_BIN_NAME` — The name of the binary that is currently being compiled (if it is a binary). This name does not include any file extension, such as `.exe`.
215* `OUT_DIR` — If the package has a build script, this is set to the folder where the build
216              script should place its output. See below for more information.
217              (Only set during compilation.)
218* `CARGO_BIN_EXE_<name>` — The absolute path to a binary target's executable.
219  This is only set when building an [integration test] or benchmark. This may
220  be used with the [`env` macro] to find the executable to run for testing
221  purposes. The `<name>` is the name of the binary target, exactly as-is. For
222  example, `CARGO_BIN_EXE_my-program` for a binary named `my-program`.
223  Binaries are automatically built when the test is built, unless the binary
224  has required features that are not enabled.
225* `CARGO_PRIMARY_PACKAGE` — This environment variable will be set if the
226  package being built is primary. Primary packages are the ones the user
227  selected on the command-line, either with `-p` flags or the defaults based
228  on the current directory and the default workspace members. This environment
229  variable will not be set when building dependencies. This is only set when
230  compiling the package (not when running binaries or tests).
231* `CARGO_TARGET_TMPDIR` — Only set when building [integration test] or benchmark code.
232  This is a path to a directory inside the target directory
233  where integration tests or benchmarks are free to put any data needed by
234  the tests/benches. Cargo initially creates this directory but doesn't
235  manage its content in any way, this is the responsibility of the test code.
236
237[integration test]: cargo-targets.md#integration-tests
238[`env` macro]: ../../std/macro.env.html
239
240#### Dynamic library paths
241
242Cargo also sets the dynamic library path when compiling and running binaries
243with commands like `cargo run` and `cargo test`. This helps with locating
244shared libraries that are part of the build process. The variable name depends
245on the platform:
246
247* Windows: `PATH`
248* macOS: `DYLD_FALLBACK_LIBRARY_PATH`
249* Unix: `LD_LIBRARY_PATH`
250
251The value is extended from the existing value when Cargo starts. macOS has
252special consideration where if `DYLD_FALLBACK_LIBRARY_PATH` is not already
253set, it will add the default `$HOME/lib:/usr/local/lib:/usr/lib`.
254
255Cargo includes the following paths:
256
257* Search paths included from any build script with the [`rustc-link-search`
258  instruction](build-scripts.md#rustc-link-search). Paths outside of the
259  `target` directory are removed. It is the responsibility of the user running
260  Cargo to properly set the environment if additional libraries on the system
261  are needed in the search path.
262* The base output directory, such as `target/debug`, and the "deps" directory.
263  This is mostly for legacy support of `rustc` compiler plugins.
264* The rustc sysroot library path. This generally is not important to most
265  users.
266
267### Environment variables Cargo sets for build scripts
268
269Cargo sets several environment variables when build scripts are run. Because these variables
270are not yet set when the build script is compiled, the above example using `env!` won't work
271and instead you'll need to retrieve the values when the build script is run:
272
273```rust,ignore
274use std::env;
275let out_dir = env::var("OUT_DIR").unwrap();
276```
277
278`out_dir` will now contain the value of `OUT_DIR`.
279
280* `CARGO` — Path to the `cargo` binary performing the build.
281* `CARGO_MANIFEST_DIR` — The directory containing the manifest for the package
282                         being built (the package containing the build
283                         script). Also note that this is the value of the
284                         current working directory of the build script when it
285                         starts.
286* `CARGO_MANIFEST_LINKS` — the manifest `links` value.
287* `CARGO_MAKEFLAGS` — Contains parameters needed for Cargo's [jobserver]
288                      implementation to parallelize subprocesses.
289                      Rustc or cargo invocations from build.rs can already
290                      read `CARGO_MAKEFLAGS`, but GNU Make requires the
291                      flags to be specified either directly as arguments,
292                      or through the `MAKEFLAGS` environment variable.
293                      Currently Cargo doesn't set the `MAKEFLAGS` variable,
294                      but it's free for build scripts invoking GNU Make
295                      to set it to the contents of `CARGO_MAKEFLAGS`.
296* `CARGO_FEATURE_<name>` — For each activated feature of the package being
297                           built, this environment variable will be present
298                           where `<name>` is the name of the feature uppercased
299                           and having `-` translated to `_`.
300* `CARGO_CFG_<cfg>` — For each [configuration option][configuration] of the
301  package being built, this environment variable will contain the value of the
302  configuration, where `<cfg>` is the name of the configuration uppercased and
303  having `-` translated to `_`. Boolean configurations are present if they are
304  set, and not present otherwise. Configurations with multiple values are
305  joined to a single variable with the values delimited by `,`. This includes
306  values built-in to the compiler (which can be seen with `rustc --print=cfg`)
307  and values set by build scripts and extra flags passed to `rustc` (such as
308  those defined in `RUSTFLAGS`). Some examples of what these variables are:
309    * `CARGO_CFG_UNIX` — Set on [unix-like platforms].
310    * `CARGO_CFG_WINDOWS` — Set on [windows-like platforms].
311    * `CARGO_CFG_TARGET_FAMILY=unix` — The [target family], either `unix` or `windows`.
312    * `CARGO_CFG_TARGET_OS=macos` — The [target operating system].
313    * `CARGO_CFG_TARGET_ARCH=x86_64` — The CPU [target architecture].
314    * `CARGO_CFG_TARGET_VENDOR=apple` — The [target vendor].
315    * `CARGO_CFG_TARGET_ENV=gnu` — The [target environment] ABI.
316    * `CARGO_CFG_TARGET_POINTER_WIDTH=64` — The CPU [pointer width].
317    * `CARGO_CFG_TARGET_ENDIAN=little` — The CPU [target endianness].
318    * `CARGO_CFG_TARGET_FEATURE=mmx,sse` — List of CPU [target features] enabled.
319* `OUT_DIR` — the folder in which all output should be placed. This folder is
320              inside the build directory for the package being built, and it is
321              unique for the package in question.
322* `TARGET` — the target triple that is being compiled for. Native code should be
323             compiled for this triple. See the [Target Triple] description
324             for more information.
325* `HOST` — the host triple of the Rust compiler.
326* `NUM_JOBS` — the parallelism specified as the top-level parallelism. This can
327               be useful to pass a `-j` parameter to a system like `make`. Note
328               that care should be taken when interpreting this environment
329               variable. For historical purposes this is still provided but
330               recent versions of Cargo, for example, do not need to run `make
331               -j`, and instead can set the `MAKEFLAGS` env var to the content
332               of `CARGO_MAKEFLAGS` to activate the use of Cargo's GNU Make
333               compatible [jobserver] for sub-make invocations.
334* `OPT_LEVEL`, `DEBUG` — values of the corresponding variables for the
335                         profile currently being built.
336* `PROFILE` — `release` for release builds, `debug` for other builds. This is
337  determined based on if the [profile] inherits from the [`dev`] or
338  [`release`] profile. Using this environment variable is not recommended.
339  Using other environment variables like `OPT_LEVEL` provide a more correct
340  view of the actual settings being used.
341* `DEP_<name>_<key>` — For more information about this set of environment
342                       variables, see build script documentation about [`links`][links].
343* `RUSTC`, `RUSTDOC` — the compiler and documentation generator that Cargo has
344                       resolved to use, passed to the build script so it might
345                       use it as well.
346* `RUSTC_WRAPPER` — the `rustc` wrapper, if any, that Cargo is using.
347                    See [`build.rustc-wrapper`].
348* `RUSTC_WORKSPACE_WRAPPER` — the `rustc` wrapper, if any, that Cargo is
349			      using for workspace members. See
350			      [`build.rustc-workspace-wrapper`].
351* `RUSTC_LINKER` — The path to the linker binary that Cargo has resolved to use
352                   for the current target, if specified. The linker can be
353                   changed by editing `.cargo/config.toml`; see the documentation
354                   about [cargo configuration][cargo-config] for more
355                   information.
356* `CARGO_ENCODED_RUSTFLAGS` — extra flags that Cargo invokes `rustc`
357			      with, separated by a `0x1f` character
358			      (ASCII Unit Separator). See
359			      [`build.rustflags`].
360* `CARGO_PKG_<var>` - The package information variables, with the same names and values as are [provided during crate building][variables set for crates].
361
362[unix-like platforms]: ../../reference/conditional-compilation.html#unix-and-windows
363[windows-like platforms]: ../../reference/conditional-compilation.html#unix-and-windows
364[target family]: ../../reference/conditional-compilation.html#target_family
365[target operating system]: ../../reference/conditional-compilation.html#target_os
366[target architecture]: ../../reference/conditional-compilation.html#target_arch
367[target vendor]: ../../reference/conditional-compilation.html#target_vendor
368[target environment]: ../../reference/conditional-compilation.html#target_env
369[pointer width]: ../../reference/conditional-compilation.html#target_pointer_width
370[target endianness]: ../../reference/conditional-compilation.html#target_endian
371[target features]: ../../reference/conditional-compilation.html#target_feature
372[links]: build-scripts.md#the-links-manifest-key
373[configuration]: ../../reference/conditional-compilation.html
374[jobserver]: https://www.gnu.org/software/make/manual/html_node/Job-Slots.html
375[cargo-config]: config.md
376[Target Triple]: ../appendix/glossary.md#target
377[variables set for crates]: #environment-variables-cargo-sets-for-crates
378[profile]: profiles.md
379[`dev`]: profiles.md#dev
380[`release`]: profiles.md#release
381
382### Environment variables Cargo sets for 3rd party subcommands
383
384Cargo exposes this environment variable to 3rd party subcommands
385(ie. programs named `cargo-foobar` placed in `$PATH`):
386
387* `CARGO` — Path to the `cargo` binary performing the build.
388
389For extended information about your environment you may run `cargo metadata`.
390