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:
You can override these environment variables to change Cargo’s behavior on your system:
CARGO_LOG— Cargo uses the
tracingcrate to display debug log messages. The
CARGO_LOGenvironment variable can be set to enable debug logging, with a value such as
warn. Usually it is only used during debugging. For more details refer to the Debug logging.
CARGO_HOME— Cargo maintains a local cache of the registry index and of git checkouts of crates. By default these are stored under
%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.
CARGO— If set, Cargo will forward this value instead of setting it to its own auto-detected path when it builds crates and when it executes build scripts and external subcommands. This value is not directly executed by Cargo, and should always point at a command that behaves exactly like
cargo, as that’s what users of the variable will be expecting.
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, passing as its command-line arguments the rustc invocation, with the first argument being the path to the actual rustc. Useful to set up a build cache tool such as
build.rustc-wrapperto set via config. Setting this to the empty string overwrites the config and resets cargo to not use a wrapper.
RUSTC_WORKSPACE_WRAPPER— Instead of simply running
rustc, for workspace members Cargo will execute this specified wrapper, passing as its command-line arguments the rustc invocation, with the first argument being the path to the actual rustc. It affects the filename hash so that artifacts produced by the wrapper are cached separately. See
build.rustc-workspace-wrapperto set via config. Setting this to the empty string overwrites the config and resets cargo to not use a wrapper for workspace members.
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
build.rustdocflagsfor some more ways to set flags. This string is split by whitespace; for a more robust encoding of multiple arguments, see
CARGO_ENCODED_RUSTDOCFLAGS— A list of custom flags separated by
0x1f(ASCII Unit Separator) to pass to all
rustdocinvocations that Cargo performs.
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. This string is split by whitespace; for a more robust encoding of multiple arguments, see
CARGO_ENCODED_RUSTFLAGS— A list of custom flags separated by
0x1f(ASCII Unit Separator) to pass to all compiler invocations that Cargo performs.
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
CARGO_CACHE_RUSTC_INFO— If this is set to 0 then Cargo will not try to cache compiler version information.
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
doc.browserfor more details.
RUSTFMT— Instead of running
cargo fmtwill execute this specified
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
CARGO_BUILD_JOBS— Number of parallel jobs, see
rustcwrapper for workspace members only, see
CARGO_BUILD_TARGET— The default target platform, see
CARGO_BUILD_TARGET_DIR— The default output directory, see
CARGO_BUILD_INCREMENTAL— Incremental compilation, see
CARGO_BUILD_DEP_INFO_BASEDIR— Dep-info relative directory, see
CARGO_CARGO_NEW_VCS— The default source control system with
cargo new, see
CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCY— How often we should generate a future incompat report notification, see
CARGO_HTTP_DEBUG— Enables HTTP debugging, see
CARGO_HTTP_PROXY— Enables HTTP proxy, see
CARGO_HTTP_TIMEOUT— The HTTP timeout, see
CARGO_HTTP_CAINFO— The TLS certificate Certificate Authority file, see
CARGO_HTTP_CHECK_REVOKE— Disables TLS certificate revocation checks, see
CARGO_HTTP_SSL_VERSION— The TLS version to use, see
CARGO_HTTP_LOW_SPEED_LIMIT— The HTTP low-speed limit, see
CARGO_HTTP_MULTIPLEXING— Whether HTTP/2 multiplexing is used, see
CARGO_HTTP_USER_AGENT— The HTTP user-agent header, see
CARGO_INSTALL_ROOT— The default directory for
cargo install, see
CARGO_NET_RETRY— Number of times to retry network errors, see
CARGO_NET_GIT_FETCH_WITH_CLI— Enables the use of the
gitexecutable to fetch, see
CARGO_NET_OFFLINE— Offline mode, see
CARGO_PROFILE_<name>_BUILD_OVERRIDE_<key>— Override build script profile, see
CARGO_PROFILE_<name>_CODEGEN_UNITS— Set code generation units, see
CARGO_PROFILE_<name>_DEBUG— What kind of debug info to include, see
CARGO_PROFILE_<name>_DEBUG_ASSERTIONS— Enable/disable debug assertions, see
CARGO_PROFILE_<name>_INCREMENTAL— Enable/disable incremental compilation, see
CARGO_PROFILE_<name>_LTO— Link-time optimization, see
CARGO_PROFILE_<name>_OVERFLOW_CHECKS— Enable/disable overflow checks, see
CARGO_PROFILE_<name>_OPT_LEVEL— Set the optimization level, see
CARGO_PROFILE_<name>_PANIC— The panic strategy to use, see
CARGO_PROFILE_<name>_RPATH— The rpath linking option, see
CARGO_PROFILE_<name>_SPLIT_DEBUGINFO— Controls debug file output behavior, see
CARGO_PROFILE_<name>_STRIP— Controls stripping of symbols and/or debuginfos, see
CARGO_REGISTRIES_<name>_INDEX— URL of a registry index, see
CARGO_REGISTRIES_<name>_TOKEN— Authentication token of a registry, see
CARGO_REGISTRY_DEFAULT— Default registry for the
CARGO_REGISTRY_TOKEN— Authentication token for crates.io, see
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
rustcflags for a target, see
CARGO_TERM_QUIET— Quiet mode, see
CARGO_TERM_VERBOSE— The default terminal verbosity, see
CARGO_TERM_COLOR— The default color mode, see
CARGO_TERM_PROGRESS_WHEN— The default progress bar showing mode, see
CARGO_TERM_PROGRESS_WIDTH— The default progress bar width, see
Cargo exposes these environment variables to your crate when it is compiled.
Note that this applies for running binaries with
cargo run and
as well. To get the value of any of these variables in a Rust program, do
let version = env!("CARGO_PKG_VERSION");
version will now contain the value of
Note that if one of these values is not provided in the manifest, the
corresponding environment variable is set to the empty string,
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.
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 the current 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
_, 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 any file extension, such as
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.
CARGO_PRIMARY_PACKAGE— This environment variable will be set if the package being built is primary. Primary packages are the ones the user selected on the command-line, either with
-pflags or the defaults based on the current directory and the default workspace members. This environment variable will not be set when building dependencies. This is only set when compiling 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 directory where integration tests or benchmarks are free to put any data needed by the tests/benches. Cargo initially creates this directory but doesn’t manage its content in any way, this is the responsibility of the test code.
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:
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
Cargo includes the following paths:
- Search paths included from any build script with the
rustc-link-searchinstruction. Paths outside of the
targetdirectory 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 of
- The rustc sysroot library path. This generally is not important to most users.
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:
use std::env; let out_dir = env::var("OUT_DIR").unwrap();
out_dir will now contain the value of
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
CARGO_MAKEFLAGS— Contains parameters needed for Cargo’s jobserver implementation to parallelize subprocesses. Rustc or cargo invocations from build.rs can already read
CARGO_MAKEFLAGS, but GNU Make requires the flags to be specified either directly as arguments, or through the
MAKEFLAGSenvironment variable. Currently Cargo doesn’t set the
MAKEFLAGSvariable, but it’s free for build scripts invoking GNU Make to set it to the contents of
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
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
_. 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.
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 and intermediate artifacts 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 -j, and instead can set the
MAKEFLAGSenv var to the content of
CARGO_MAKEFLAGSto activate the use of Cargo’s GNU Make compatible jobserver for sub-make invocations.
DEBUG— values of the corresponding variables for the profile currently being built.
releasefor release builds,
debugfor other builds. This is determined based on if the profile inherits from the
releaseprofile. Using this environment variable is not recommended. Using other environment variables like
OPT_LEVELprovide a more correct view of the actual settings being used.
DEP_<name>_<key>— For more information about this set of environment variables, see build script documentation about
RUSTDOC— the compiler and documentation generator that Cargo has resolved to use, passed to the build script so it might use it as well.
rustcwrapper, if any, that Cargo is using. See
rustcwrapper, if any, that Cargo is using for workspace members. See
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.toml; see the documentation about cargo configuration for more information.
CARGO_ENCODED_RUSTFLAGS— extra flags that Cargo invokes
rustcwith, separated by a
0x1fcharacter (ASCII Unit Separator). See
build.rustflags. Note that since Rust 1.55,
RUSTFLAGSis removed from the environment; scripts should use
CARGO_PKG_<var>— The package information variables, with the same names and values as are provided during crate building.
Cargo exposes this environment variable to 3rd party subcommands
(ie. programs named
cargo-foobar placed in
CARGO— Path to the
cargobinary performing the build.
For extended information about your environment you may run