Environment Variables
Cargo sets and reads a number of environment variables which your code can detect or override. Here is a list of the variables Cargo sets, organized by when it interacts with them:
Environment variables Cargo reads
You can override these environment variables to change Cargo's behavior on your system:
- CARGO_HOME— Cargo maintains a local cache of the registry index and of git checkouts of crates. By default these are stored under- $HOME/.cargo(- %USERPROFILE%\.cargoon Windows), but this variable overrides the location of this directory. Once a crate is cached it is not removed by the clean command. For more details refer to the guide.
- CARGO_TARGET_DIR— Location of where to place all generated artifacts, relative to the current working directory. See- build.target-dirto set via config.
- RUSTC— Instead of running- rustc, Cargo will execute this specified compiler instead. See- build.rustcto set via config.
- RUSTC_WRAPPER— Instead of simply running- rustc, Cargo will execute this specified wrapper instead, passing as its commandline arguments the rustc invocation, with the first argument being- rustc. Useful to set up a build cache tool such as- sccache. See- build.rustc-wrapperto set via config.
- RUSTDOC— Instead of running- rustdoc, Cargo will execute this specified- rustdocinstance instead. See- build.rustdocto set via config.
- RUSTDOCFLAGS— A space-separated list of custom flags to pass to all- rustdocinvocations that Cargo performs. In contrast with [- cargo rustdoc], this is useful for passing a flag to all- rustdocinstances. See- build.rustdocflagsfor some more ways to set flags.
- RUSTFLAGS— A space-separated list of custom flags to pass to all compiler invocations that Cargo performs. In contrast with- cargo rustc, this is useful for passing a flag to all compiler instances. See- build.rustflagsfor some more ways to set flags.
- CARGO_INCREMENTAL— If this is set to 1 then Cargo will force incremental compilation to be enabled for the current compilation, and when set to 0 it will force disabling it. If this env var isn't present then cargo's defaults will otherwise be used. See also- build.incrementalconfig value.
- CARGO_CACHE_RUSTC_INFO— If this is set to 0 then Cargo will not try to cache compiler version information.
- CARGO_NAME— The author name to use for- cargo new.
- CARGO_EMAIL— The author email to use for- cargo new.
- HTTPS_PROXYor- https_proxyor- http_proxy— The HTTP proxy to use, see- http.proxyfor more detail.
- HTTP_TIMEOUT— The HTTP timeout in seconds, see- http.timeoutfor more detail.
- TERM— If this is set to- dumb, it disables the progress bar.
- BROWSER— The web browser to execute to open documentation with- cargo doc's'- --openflag.
Configuration environment variables
Cargo reads environment variables for configuration values. See the configuration chapter for more details. In summary, the supported environment variables are:
- CARGO_ALIAS_<name>— Command aliases, see- alias.
- CARGO_BUILD_JOBS— Number of parallel jobs, see- build.jobs.
- CARGO_BUILD_RUSTC— The- rustcexecutable, see- build.rustc.
- CARGO_BUILD_RUSTC_WRAPPER— The- rustcwrapper, see- build.rustc-wrapper.
- CARGO_BUILD_RUSTDOC— The- rustdocexecutable, see- build.rustdoc.
- CARGO_BUILD_TARGET— The default target platform, see- build.target.
- CARGO_BUILD_TARGET_DIR— The default output directory, see- build.target-dir.
- CARGO_BUILD_RUSTFLAGS— Extra- rustcflags, see- build.rustflags.
- CARGO_BUILD_RUSTDOCFLAGS— Extra- rustdocflags, see- build.rustdocflags.
- CARGO_BUILD_INCREMENTAL— Incremental compilation, see- build.incremental.
- CARGO_BUILD_DEP_INFO_BASEDIR— Dep-info relative directory, see- build.dep-info-basedir.
- CARGO_BUILD_PIPELINING— Whether or not to use- rustcpipelining, see- build.pipelining.
- CARGO_CARGO_NEW_NAME— The author name to use with- cargo new, see- cargo-new.name.
- CARGO_CARGO_NEW_EMAIL— The author email to use with- cargo new, see- cargo-new.email.
- CARGO_CARGO_NEW_VCS— The default source control system with- cargo new, see- cargo-new.vcs.
- CARGO_HTTP_DEBUG— Enables HTTP debugging, see- http.debug.
- CARGO_HTTP_PROXY— Enables HTTP proxy, see- http.proxy.
- CARGO_HTTP_TIMEOUT— The HTTP timeout, see- http.timeout.
- CARGO_HTTP_CAINFO— The TLS certificate Certificate Authority file, see- http.cainfo.
- CARGO_HTTP_CHECK_REVOKE— Disables TLS certificate revocation checks, see- http.check-revoke.
- CARGO_HTTP_SSL_VERSION— The TLS version to use, see- http.ssl-version.
- CARGO_HTTP_LOW_SPEED_LIMIT— The HTTP low-speed limit, see- http.low-speed-limit.
- CARGO_HTTP_MULTIPLEXING— Whether HTTP/2 multiplexing is used, see- http.multiplexing.
- CARGO_HTTP_USER_AGENT— The HTTP user-agent header, see- http.user-agent.
- CARGO_INSTALL_ROOT— The default directory for- cargo install, see- install.root.
- CARGO_NET_RETRY— Number of times to retry network errors, see- net.retry.
- CARGO_NET_GIT_FETCH_WITH_CLI— Enables the use of the- gitexecutable to fetch, see- net.git-fetch-with-cli.
- CARGO_NET_OFFLINE— Offline mode, see- net.offline.
- CARGO_PROFILE_<name>_BUILD_OVERRIDE_<key>— Override build script profile, see- profile.<name>.build-override.
- CARGO_PROFILE_<name>_CODEGEN_UNITS— Set code generation units, see- profile.<name>.codegen-units.
- CARGO_PROFILE_<name>_DEBUG— What kind of debug info to include, see- profile.<name>.debug.
- CARGO_PROFILE_<name>_DEBUG_ASSERTIONS— Enable/disable debug assertions, see- profile.<name>.debug-assertions.
- CARGO_PROFILE_<name>_INCREMENTAL— Enable/disable incremental compilation, see- profile.<name>.incremental.
- CARGO_PROFILE_<name>_LTO— Link-time optimization, see- profile.<name>.lto.
- CARGO_PROFILE_<name>_OVERFLOW_CHECKS— Enable/disable overflow checks, see- profile.<name>.overflow-checks.
- CARGO_PROFILE_<name>_OPT_LEVEL— Set the optimization level, see- profile.<name>.opt-level.
- CARGO_PROFILE_<name>_PANIC— The panic strategy to use, see- profile.<name>.panic.
- CARGO_PROFILE_<name>_RPATH— The rpath linking option, see- profile.<name>.rpath.
- CARGO_REGISTRIES_<name>_INDEX— URL of a registry index, see- registries.<name>.index.
- CARGO_REGISTRIES_<name>_TOKEN— Authentication token of a registry, see- registries.<name>.token.
- CARGO_REGISTRY_DEFAULT— Default registry for the- --registryflag, see- registry.default.
- CARGO_REGISTRY_TOKEN— Authentication token for crates.io, see- registry.token.
- CARGO_TARGET_<triple>_LINKER— The linker to use, see- target.<triple>.linker.
- CARGO_TARGET_<triple>_RUNNER— The executable runner, see- target.<triple>.runner.
- CARGO_TARGET_<triple>_RUSTFLAGS— Extra- rustcflags for a target, see- target.<triple>.rustflags.
- CARGO_TERM_VERBOSE— The default terminal verbosity, see- term.verbose.
- CARGO_TERM_COLOR— The default color mode, see- term.color.
Environment variables Cargo sets for crates
Cargo exposes these environment variables to your crate when it is compiled.
Note that this applies for running binaries with cargo run and cargo test
as well. To get the value of any of these variables in a Rust program, do
this:
#![allow(unused_variables)] fn main() { let version = env!("CARGO_PKG_VERSION"); }
version will now contain the value of CARGO_PKG_VERSION.
- CARGO— Path to the- cargobinary performing the build.
- CARGO_MANIFEST_DIR— The directory containing the manifest of your package.
- CARGO_PKG_VERSION— The full version of your package.
- CARGO_PKG_VERSION_MAJOR— The major version of your package.
- CARGO_PKG_VERSION_MINOR— The minor version of your package.
- CARGO_PKG_VERSION_PATCH— The patch version of your package.
- CARGO_PKG_VERSION_PRE— The pre-release version of your package.
- CARGO_PKG_AUTHORS— Colon separated list of authors from the manifest of your package.
- CARGO_PKG_NAME— The name of your package.
- CARGO_PKG_DESCRIPTION— The description from the manifest of your package.
- CARGO_PKG_HOMEPAGE— The home page from the manifest of your package.
- CARGO_PKG_REPOSITORY— The repository from the manifest of your package.
- OUT_DIR— If the package has a build script, this is set to the folder where the build script should place its output. See below for more information. (Only set during compilation.)
- CARGO_BIN_EXE_<name>— The absolute path to a binary target's executable. This is only set when building an integration test or benchmark. This may be used with the- envmacro to find the executable to run for testing purposes. The- <name>is the name of the binary target, exactly as-is. For example,- CARGO_BIN_EXE_my-programfor a binary named- my-program. Binaries are automatically built when the test is built, unless the binary has required features that are not enabled.
Dynamic library paths
Cargo also sets the dynamic library path when compiling and running binaries
with commands like cargo run and cargo test. This helps with locating
shared libraries that are part of the build process. The variable name depends
on the platform:
- Windows: PATH
- macOS: DYLD_FALLBACK_LIBRARY_PATH
- Unix: LD_LIBRARY_PATH
The value is extended from the existing value when Cargo starts. macOS has
special consideration where if DYLD_FALLBACK_LIBRARY_PATH is not already
set, it will add the default $HOME/lib:/usr/local/lib:/usr/lib.
Cargo includes the following paths:
- Search paths included from any build script with the rustc-link-searchinstruction. Paths outside of thetargetdirectory are removed. It is the responsibility of the user running Cargo to properly set the environment if additional libraries on the system are needed in the search path.
- The base output directory, such as target/debug, and the "deps" directory. This is mostly for legacy support ofrustccompiler plugins.
- The rustc sysroot library path. This generally is not important to most users.
Environment variables Cargo sets for build scripts
Cargo sets several environment variables when build scripts are run. Because these variables
are not yet set when the build script is compiled, the above example using env! won't work
and instead you'll need to retrieve the values when the build script is run:
#![allow(unused_variables)] fn main() { use std::env; let out_dir = env::var("OUT_DIR").unwrap(); }
out_dir will now contain the value of OUT_DIR.
- CARGO— Path to the- cargobinary performing the build.
- CARGO_MANIFEST_DIR— The directory containing the manifest for the package being built (the package containing the build script). Also note that this is the value of the current working directory of the build script when it starts.
- CARGO_MANIFEST_LINKS— the manifest- linksvalue.
- CARGO_FEATURE_<name>— For each activated feature of the package being built, this environment variable will be present where- <name>is the name of the feature uppercased and having- -translated to- _.
- CARGO_CFG_<cfg>— For each configuration option of the package being built, this environment variable will contain the value of the configuration, where- <cfg>is the name of the configuration uppercased and having- -translated to- _. Boolean configurations are present if they are set, and not present otherwise. Configurations with multiple values are joined to a single variable with the values delimited by- ,. This includes values built-in to the compiler (which can be seen with- rustc --print=cfg) and values set by build scripts and extra flags passed to- rustc(such as those defined in- RUSTFLAGS). Some examples of what these variables are:- CARGO_CFG_UNIX— Set on unix-like platforms.
- CARGO_CFG_WINDOWS— Set on windows-like platforms.
- CARGO_CFG_TARGET_FAMILY=unix— The target family, either- unixor- windows.
- CARGO_CFG_TARGET_OS=macos— The target operating system.
- CARGO_CFG_TARGET_ARCH=x86_64— The CPU target architecture.
- CARGO_CFG_TARGET_VENDOR=apple— The target vendor.
- CARGO_CFG_TARGET_ENV=gnu— The target environment ABI.
- CARGO_CFG_TARGET_POINTER_WIDTH=64— The CPU pointer width.
- CARGO_CFG_TARGET_ENDIAN=little— The CPU target endianness.
- CARGO_CFG_TARGET_FEATURE=mmx,sse— List of CPU target features enabled.
 
- OUT_DIR— the folder in which all output should be placed. This folder is inside the build directory for the package being built, and it is unique for the package in question.
- TARGET— the target triple that is being compiled for. Native code should be compiled for this triple. See the Target Triple description for more information.
- HOST— the host triple of the rust compiler.
- NUM_JOBS— the parallelism specified as the top-level parallelism. This can be useful to pass a- -jparameter to a system like- make. Note that care should be taken when interpreting this environment variable. For historical purposes this is still provided but recent versions of Cargo, for example, do not need to run- make -jas it'll automatically happen. Cargo implements its own jobserver and will allow build scripts to inherit this information, so programs compatible with GNU make jobservers will already have appropriately configured parallelism.
- OPT_LEVEL,- DEBUG— values of the corresponding variables for the profile currently being built.
- PROFILE—- releasefor release builds,- debugfor other builds.
- DEP_<name>_<key>— For more information about this set of environment variables, see build script documentation about- links.
- RUSTC,- RUSTDOC— the compiler and documentation generator that Cargo has resolved to use, passed to the build script so it might use it as well.
- RUSTC_LINKER— The path to the linker binary that Cargo has resolved to use for the current target, if specified. The linker can be changed by editing- .cargo/config; see the documentation about cargo configuration for more information.
Environment variables Cargo sets for 3rd party subcommands
Cargo exposes this environment variable to 3rd party subcommands
(ie. programs named cargo-foobar placed in $PATH):
- CARGO— Path to the- cargobinary performing the build.