Cargo sets and reads a number of environment variables which your code can detector override. Here is a list of the variables Cargo sets, organized by when it interactswith them:
Environment variables Cargo reads
You can override these environment variables to change Cargo’s behavior on yoursystem:
CARGO_LOG
— Cargo uses thetracing
crate to display debug log messages.TheCARGO_LOG
environment variable can be set to enable debug logging,with a value such astrace
,debug
, orwarn
.Usually it is only used during debugging. For more details refer to theDebug logging.CARGO_HOME
— Cargo maintains a local cache of the registry index and ofgit checkouts of crates. By default these are stored under$HOME/.cargo
(%USERPROFILE%\.cargo
on Windows), but this variable overrides thelocation of this directory. Once a crate is cached it is not removed by theclean 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-dir to setvia config.CARGO
— If set, Cargo will forward this value instead of setting itto its own auto-detected path when it builds crates and when itexecutes build scripts and external subcommands. This value is notdirectly executed by Cargo, and should always point at a command thatbehaves exactly likecargo
, as that’s what users of the variablewill be expecting.RUSTC
— Instead of runningrustc
, Cargo will execute this specifiedcompiler instead. See build.rustc to set via config.RUSTC_WRAPPER
— Instead of simply runningrustc
, Cargo will execute thisspecified wrapper, passing as its command-line arguments the rustcinvocation, with the first argument being the path to the actual rustc.Useful to set up a build cache tool such assccache
. Seebuild.rustc-wrapper to set via config. Setting this to the empty stringoverwrites the config and resets cargo to not use a wrapper.RUSTC_WORKSPACE_WRAPPER
— Instead of simply runningrustc
, for workspace members Cargo willexecute this specified wrapper, passing as its command-line arguments the rustc invocation, withthe first argument being the path to the actual rustc. When building a single-package projectwithout workspaces, that package is considered to be the workspace. It affects the filename hashso that artifacts produced by the wrapper are cached separately. Seebuild.rustc-workspace-wrapper to set via config. Setting this to the empty string overwritesthe config and resets cargo to not use a wrapper for workspace members. If bothRUSTC_WRAPPER
andRUSTC_WORKSPACE_WRAPPER
are set, then they will be nested: the final invocation is$RUSTC_WRAPPER $RUSTC_WORKSPACE_WRAPPER $RUSTC
.RUSTDOC
— Instead of runningrustdoc
, Cargo will execute this specifiedrustdoc
instance instead. See build.rustdoc to set via config.RUSTDOCFLAGS
— A space-separated list of custom flags to pass to allrustdoc
invocations that Cargo performs. In contrast with cargo rustdoc, this isuseful for passing a flag to allrustdoc
instances. Seebuild.rustdocflags for some more ways to set flags. This string issplit by whitespace; for a more robust encoding of multiple arguments,seeCARGO_ENCODED_RUSTDOCFLAGS
.CARGO_ENCODED_RUSTDOCFLAGS
— A list of custom flags separated by0x1f
(ASCII Unit Separator) to pass to allrustdoc
invocations that Cargo performs.RUSTFLAGS
— A space-separated list of custom flags to pass to all compilerinvocations that Cargo performs. In contrast with cargo rustc, this isuseful for passing a flag to all compiler instances. Seebuild.rustflags for some more ways to set flags. This string issplit by whitespace; for a more robust encoding of multiple arguments,seeCARGO_ENCODED_RUSTFLAGS
.CARGO_ENCODED_RUSTFLAGS
— A list of custom flags separated by0x1f
(ASCII Unit Separator) to pass to all compiler invocations that Cargo performs.CARGO_INCREMENTAL
— If this is set to 1 then Cargo will force incrementalcompilation to be enabled for the current compilation, and when set to 0 itwill force disabling it. If this env var isn’t present then cargo’s defaultswill otherwise be used. See also build.incremental config value.CARGO_CACHE_RUSTC_INFO
— If this is set to 0 then Cargo will not try to cachecompiler version information.HTTPS_PROXY
orhttps_proxy
orhttp_proxy
— The HTTP proxy to use, seehttp.proxy for more detail.HTTP_TIMEOUT
— The HTTP timeout in seconds, see http.timeout for moredetail.TERM
— If this is set todumb
, it disables the progress bar.BROWSER
— The web browser to execute to open documentation with cargo doc’s’--open
flag, see doc.browser for more details.RUSTFMT
— Instead of runningrustfmt
,cargo fmt
will execute this specifiedrustfmt
instance instead.
Configuration environment variables
Cargo reads environment variables for some 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
— Therustc
executable, see build.rustc.CARGO_BUILD_RUSTC_WRAPPER
— Therustc
wrapper, see build.rustc-wrapper.CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER
— Therustc
wrapper for workspace members only, see build.rustc-workspace-wrapper.CARGO_BUILD_RUSTDOC
— Therustdoc
executable, 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
— Extrarustc
flags, see build.rustflags.CARGO_BUILD_RUSTDOCFLAGS
— Extrarustdoc
flags, 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_CARGO_NEW_VCS
— The default source control system with cargo new, see cargo-new.vcs.CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCY
— How often we should generate a future incompat report notification, see future-incompat-report.frequency.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 thegit
executable 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_PROFILE_<name>_SPLIT_DEBUGINFO
— Controls debug file output behavior, see profile.<name>.split-debuginfo.CARGO_PROFILE_<name>_STRIP
— Controls stripping of symbols and/or debuginfos, see profile.<name>.strip.CARGO_REGISTRIES_<name>_CREDENTIAL_PROVIDER
— Credential provider for a registry, see registries.<name>.credential-provider.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_CREDENTIAL_PROVIDER
— Credential provider for crates.io, see registry.credential-provider.CARGO_REGISTRY_DEFAULT
— Default registry for the--registry
flag, see registry.default.CARGO_REGISTRY_GLOBAL_CREDENTIAL_PROVIDERS
— Credential providers for registries that do not have a specific provider defined. See registry.global-credential-providers.CARGO_REGISTRY_TOKEN
— Authentication token for crates.io, see registry.token.CARGO_TARGET_<triple>_LINKER
— The linker to use, see target.<triple>.linker. The triple must be converted to uppercase and underscores.CARGO_TARGET_<triple>_RUNNER
— The executable runner, see target.<triple>.runner.CARGO_TARGET_<triple>_RUSTFLAGS
— Extrarustc
flags for a target, see target.<triple>.rustflags.CARGO_TERM_QUIET
— Quiet mode, see term.quiet.CARGO_TERM_VERBOSE
— The default terminal verbosity, see term.verbose.CARGO_TERM_COLOR
— The default color mode, see term.color.CARGO_TERM_PROGRESS_WHEN
— The default progress bar showing mode, see term.progress.when.CARGO_TERM_PROGRESS_WIDTH
— The default progress bar width, see term.progress.width.
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, dothis:
let version = env!("CARGO_PKG_VERSION");
version
will now contain the value of CARGO_PKG_VERSION
.
Note that if one of these values is not provided in the manifest, thecorresponding environment variable is set to the empty string, ""
.
CARGO
— Path to thecargo
binary 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.CARGO_PKG_LICENSE
— The license from the manifest of your package.CARGO_PKG_LICENSE_FILE
— The license file from the manifest of your package.CARGO_PKG_RUST_VERSION
— The Rust version from the manifest of your package.Note that this is the minimum Rust version supported by the package, not thecurrent Rust version.CARGO_PKG_README
— Path to the README file of your package.CARGO_CRATE_NAME
— The name of the crate that is currently being compiled. It is the name of the Cargo target with-
converted to_
, such as the name of the library, binary, example, integration test, or benchmark.CARGO_BIN_NAME
— The name of the binary that is currently being compiled.Only set for binaries or binary examples. This name does not include anyfile extension, such as.exe
.OUT_DIR
— If the package has a build script, this is set to the folderwhere 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 maybe used with the env macro to find the executable to run for testingpurposes. The<name>
is the name of the binary target, exactly as-is. Forexample,CARGO_BIN_EXE_my-program
for a binary namedmy-program
.Binaries are automatically built when the test is built, unless the binaryhas required features that are not enabled.CARGO_PRIMARY_PACKAGE
— This environment variable will be set if thepackage being built is primary. Primary packages are the ones the userselected on the command-line, either with-p
flags or the defaults basedon the current directory and the default workspace members. This environmentvariable will not be set when building dependencies. This is only set whencompiling the package (not when running binaries or tests).CARGO_TARGET_TMPDIR
— Only set when building integration test or benchmark code.This is a path to a directory inside the target directorywhere integration tests or benchmarks are free to put any data needed bythe tests/benches. Cargo initially creates this directory but doesn’tmanage its content in any way, this is the responsibility of the test code.CARGO_RUSTC_CURRENT_DIR
— This is a path thatrustc
is invoked from (nightly only).
Dynamic library paths
Cargo also sets the dynamic library path when compiling and running binarieswith commands like cargo run
and cargo test
. This helps with locatingshared libraries that are part of the build process. The variable name dependson the platform:
- Windows:
PATH
- macOS:
DYLD_FALLBACK_LIBRARY_PATH
- Unix:
LD_LIBRARY_PATH
- AIX:
LIBPATH
The value is extended from the existing value when Cargo starts. macOS hasspecial consideration where if DYLD_FALLBACK_LIBRARY_PATH
is not alreadyset, 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 the
target
directory are removed. It is the responsibility of the user runningCargo to properly set the environment if additional libraries on the systemare needed in the search path. - The base output directory, such as
target/debug
, and the “deps” directory.This is mostly for support of proc-macros. - The rustc sysroot library path. This generally is not important to mostusers.
Environment variables Cargo sets for build scripts
Cargo sets several environment variables when build scripts are run. Because these variablesare not yet set when the build script is compiled, the above example using env!
won’t workand instead you’ll need to retrieve the values when the build script is run:
use std::env;let out_dir = env::var("OUT_DIR").unwrap();
out_dir
will now contain the value of OUT_DIR
.
CARGO
— Path to thecargo
binary performing the build.CARGO_MANIFEST_DIR
— The directory containing the manifest for the packagebeing built (the package containing the build script). Also note that this isthe value of the current working directory of the build script when it starts.CARGO_MANIFEST_LINKS
— the manifestlinks
value.CARGO_MAKEFLAGS
— Contains parameters needed for Cargo’s jobserverimplementation to parallelize subprocesses. Rustc or cargo invocations frombuild.rs can already readCARGO_MAKEFLAGS
, but GNU Make requires the flagsto be specified either directly as arguments, or through theMAKEFLAGS
environment variable. Currently Cargo doesn’t set theMAKEFLAGS
variable,but it’s free for build scripts invoking GNU Make to set it to the contentsofCARGO_MAKEFLAGS
.CARGO_FEATURE_<name>
— For each activated feature of the package being built,this environment variable will be present where<name>
is the name of thefeature uppercased and having-
translated to_
.CARGO_CFG_<cfg>
— For each configuration option of thepackage being built, this environment variable will contain the value of theconfiguration, where<cfg>
is the name of the configuration uppercased andhaving-
translated to_
. Boolean configurations are present if they areset, and not present otherwise. Configurations with multiple values arejoined to a single variable with the values delimited by,
. This includesvalues built-in to the compiler (which can be seen withrustc --print=cfg
)and values set by build scripts and extra flags passed torustc
(such asthose defined inRUSTFLAGS
). 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,wasm
— The target family.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_ABI=sim
— The target 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.
Note that different target triples have different sets of
cfg
values,hence variables present in one target triple might not be available in the other.OUT_DIR
— the folder in which all output and intermediate artifacts shouldbe 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 becompiled 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 canbe useful to pass a-j
parameter to a system likemake
. Note that careshould be taken when interpreting this environment variable. For historicalpurposes this is still provided but recent versions of Cargo, for example, donot need to runmake -j
, and instead can set theMAKEFLAGS
env var to thecontent ofCARGO_MAKEFLAGS
to activate the use of Cargo’s GNU Make compatiblejobserver for sub-make invocations.OPT_LEVEL
,DEBUG
— values of the corresponding variables for the profile currently being built.PROFILE
—release
for release builds,debug
for other builds. This isdetermined based on if the profile inherits from the dev orrelease profile. Using this environment variable is not recommended.Using other environment variables likeOPT_LEVEL
provide a more correctview of the actual settings being used.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 hasresolved to use, passed to the build script so it might use it as well.RUSTC_WRAPPER
— therustc
wrapper, if any, that Cargo is using. See build.rustc-wrapper.RUSTC_WORKSPACE_WRAPPER
— therustc
wrapper, if any, that Cargo is usingfor workspace members. See build.rustc-workspace-wrapper.RUSTC_LINKER
— The path to the linker binary that Cargo has resolved to usefor the current target, if specified. The linker can be changed by editing.cargo/config.toml
; see the documentation about cargo configurationfor more information.CARGO_ENCODED_RUSTFLAGS
— extra flags that Cargo invokesrustc
with,separated by a0x1f
character (ASCII Unit Separator). Seebuild.rustflags. Note that since Rust 1.55,RUSTFLAGS
is removed fromthe environment; scripts should useCARGO_ENCODED_RUSTFLAGS
instead.CARGO_PKG_<var>
— The package information variables, with the same names and values as are provided during crate building.
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 thecargo
binary performing the build.CARGO_MAKEFLAGS
— Contains parameters needed for Cargo’s jobserverimplementation to parallelize subprocesses.This is set only when Cargo detects the existence of a jobserver.
For extended information about your environment you may run cargo metadata
.