Configuration

This document explains how Cargo’s configuration system works, as well asavailable keys or configuration. For configuration of a package through itsmanifest, see themanifest format.

Hierarchical structure

Cargo allows local configuration for a particular package as well as globalconfiguration. It looks for configuration files in the current directory andall parent directories. If, for example, Cargo were invoked in/projects/foo/bar/baz, then the following configuration files would beprobed for and unified in this order:

/projects/foo/bar/baz/.cargo/config.toml
/projects/foo/bar/.cargo/config.toml
/projects/foo/.cargo/config.toml
/projects/.cargo/config.toml
/.cargo/config.toml
$CARGO_HOME/config.toml which defaults to:
- Windows:%USERPROFILE%\.cargo\config.toml
- Unix:$HOME/.cargo/config.toml

With this structure, you can specify configuration per-package, and evenpossibly check it into version control. You can also specify personal defaultswith a configuration file in your home directory.

If a key is specified in multiple config files, the values will get mergedtogether. Numbers, strings, and booleans will use the value in the deeperconfig directory taking precedence over ancestor directories, where thehome directory is the lowest priority. Arrays will be joined togetherwith higher precedence items being placed later in the merged array.

At present, when being invoked from a workspace, Cargo does not read configfiles from crates within the workspace. i.e. if a workspace has two crates init, named/projects/foo/bar/baz/mylib and/projects/foo/bar/baz/mybin, andthere are Cargo configs at/projects/foo/bar/baz/mylib/.cargo/config.tomland/projects/foo/bar/baz/mybin/.cargo/config.toml, Cargo does not readthose configuration files if it is invoked from the workspace root(/projects/foo/bar/baz/).

Note: Cargo also reads config files without the.toml extension, such as.cargo/config. Support for the.toml extension was added in version 1.39and is the preferred form. If both files exist, Cargo will use the filewithout the extension.

Configuration format

Configuration files are written in theTOML format (like themanifest), with simple key-value pairs inside of sections (tables). Thefollowing is a quick overview of all settings, with detailed descriptionsfound below.

paths = ["/path/to/override"] # path dependency overrides[alias]     # command aliasesb = "build"c = "check"t = "test"r = "run"rr = "run --release"recursive_example = "rr --example recursions"space_example = ["run", "--release", "--", "\"command list\""][build]jobs = 1                      # number of parallel jobs, defaults to # of CPUsrustc = "rustc"               # the rust compiler toolrustc-wrapper = "…"           # run this wrapper instead of `rustc`rustc-workspace-wrapper = "…" # run this wrapper instead of `rustc` for workspace membersrustdoc = "rustdoc"           # the doc generator tooltarget = "triple"             # build for the target triple (ignored by `cargo install`)target-dir = "target"         # path of where to place generated artifactsbuild-dir = "target"          # path of where to place intermediate build artifactsrustflags = ["…", "…"]        # custom flags to pass to all compiler invocationsrustdocflags = ["…", "…"]     # custom flags to pass to rustdocincremental = true            # whether or not to enable incremental compilationdep-info-basedir = "…"        # path for the base directory for targets in depfiles[credential-alias]# Provides a way to define aliases for credential providers.my-alias = ["/usr/bin/cargo-credential-example", "--argument", "value", "--flag"][doc]browser = "chromium"          # browser to use with `cargo doc --open`,                              # overrides the `BROWSER` environment variable[env]# Set ENV_VAR_NAME=value for any process run by CargoENV_VAR_NAME = "value"# Set even if already present in environmentENV_VAR_NAME_2 = { value = "value", force = true }# `value` is relative to the parent of `.cargo/config.toml`, env var will be the full absolute pathENV_VAR_NAME_3 = { value = "relative/path", relative = true }[future-incompat-report]frequency = 'always' # when to display a notification about a future incompat report[cache]auto-clean-frequency = "1 day"   # How often to perform automatic cache cleaning[cargo-new]vcs = "none"              # VCS to use ('git', 'hg', 'pijul', 'fossil', 'none')[http]debug = false               # HTTP debuggingproxy = "host:port"         # HTTP proxy in libcurl formatssl-version = "tlsv1.3"     # TLS version to usessl-version.max = "tlsv1.3" # maximum TLS versionssl-version.min = "tlsv1.1" # minimum TLS versiontimeout = 30                # timeout for each HTTP request, in secondslow-speed-limit = 10        # network timeout threshold (bytes/sec)cainfo = "cert.pem"         # path to Certificate Authority (CA) bundleproxy-cainfo = "cert.pem"   # path to proxy Certificate Authority (CA) bundlecheck-revoke = true         # check for SSL certificate revocationmultiplexing = true         # HTTP/2 multiplexinguser-agent = "…"            # the user-agent header[install]root = "/some/path"         # `cargo install` destination directory[net]retry = 3                   # network retriesgit-fetch-with-cli = true   # use the `git` executable for git operationsoffline = true              # do not access the network[net.ssh]known-hosts = ["..."]       # known SSH host keys[patch.<registry>]# Same keys as for [patch] in Cargo.toml[profile.<name>]         # Modify profile settings via config.inherits = "dev"         # Inherits settings from [profile.dev].opt-level = 0            # Optimization level.debug = true             # Include debug info.split-debuginfo = '...'  # Debug info splitting behavior.strip = "none"           # Removes symbols or debuginfo.debug-assertions = true  # Enables debug assertions.overflow-checks = true   # Enables runtime integer overflow checks.lto = false              # Sets link-time optimization.panic = 'unwind'         # The panic strategy.incremental = true       # Incremental compilation.codegen-units = 16       # Number of code generation units.rpath = false            # Sets the rpath linking option.[profile.<name>.build-override]  # Overrides build-script settings.# Same keys for a normal profile.[profile.<name>.package.<name>]  # Override profile for a package.# Same keys for a normal profile (minus `panic`, `lto`, and `rpath`).[resolver]incompatible-rust-versions = "allow"  # Specifies how resolver reacts to these[registries.<name>]  # registries other than crates.ioindex = "…"          # URL of the registry indextoken = "…"          # authentication token for the registrycredential-provider = "cargo:token" # The credential provider for this registry.[registries.crates-io]protocol = "sparse"  # The protocol to use to access crates.io.[registry]default = "…"        # name of the default registrytoken = "…"          # authentication token for crates.iocredential-provider = "cargo:token"           # The credential provider for crates.io.global-credential-providers = ["cargo:token"] # The credential providers to use by default.[source.<name>]      # source definition and replacementreplace-with = "…"   # replace this source with the given named sourcedirectory = "…"      # path to a directory sourceregistry = "…"       # URL to a registry sourcelocal-registry = "…" # path to a local registry sourcegit = "…"            # URL of a git repository sourcebranch = "…"         # branch name for the git repositorytag = "…"            # tag name for the git repositoryrev = "…"            # revision for the git repository[target.<triple>]linker = "…"              # linker to userunner = "…"              # wrapper to run executablesrustflags = ["…", "…"]    # custom flags for `rustc`rustdocflags = ["…", "…"] # custom flags for `rustdoc`[target.<cfg>]runner = "…"            # wrapper to run executablesrustflags = ["…", "…"]  # custom flags for `rustc`[target.<triple>.<links>] # `links` build script overriderustc-link-lib = ["foo"]rustc-link-search = ["/path/to/foo"]rustc-flags = "-L /some/path"rustc-cfg = ['key="value"']rustc-env = {key = "value"}rustc-cdylib-link-arg = ["…"]metadata_key1 = "value"metadata_key2 = "value"[term]quiet = false                    # whether cargo output is quietverbose = false                  # whether cargo provides verbose outputcolor = 'auto'                   # whether cargo colorizes outputhyperlinks = true                # whether cargo inserts links into outputunicode = true                   # whether cargo can render output using non-ASCII unicode charactersprogress.when = 'auto'           # whether cargo shows progress barprogress.width = 80              # width of progress barprogress.term-integration = true # whether cargo reports progress to terminal emulator

Environment variables

Cargo can also be configured through environment variables in addition to theTOML configuration files. For each configuration key of the formfoo.bar theenvironment variableCARGO_FOO_BAR can also be used to define the value.Keys are converted to uppercase, dots and dashes are converted to underscores.For example thetarget.x86_64-unknown-linux-gnu.runner key can also bedefined by theCARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER environmentvariable.

Environment variables will take precedence over TOML configuration files.Currently only integer, boolean, string and some array values are supported tobe defined by environment variables.Descriptions belowindicate which keys support environment variables and otherwise they are notsupported due totechnical issues.

In addition to the system above, Cargo recognizes a few other specificenvironment variables.

Command-line overrides

Cargo also accepts arbitrary configuration overrides through the--config command-line option. The argument should be in TOML syntax ofKEY=VALUE or provided as a path to an extra configuration file:

# With `KEY=VALUE` in TOML syntaxcargo --config net.git-fetch-with-cli=true fetch# With a path to a configuration filecargo --config ./path/to/my/extra-config.toml fetch

The--config option may be specified multiple times, in which case thevalues are merged in left-to-right order, using the same merging logicthat is used when multiple configuration files apply. Configurationvalues specified this way take precedence over environment variables,which take precedence over configuration files.

When the--config option is provided as an extra configuration file,The configuration file loaded this way follow the same precedence rulesas other options specified directly with--config.

Some examples of what it looks like using Bourne shell syntax:

# Most shells will require escaping.cargo --config http.proxy=\"http://example.com\" …# Spaces may be used.cargo --config "net.git-fetch-with-cli = true" …# TOML array example. Single quotes make it easier to read and write.cargo --config 'build.rustdocflags = ["--html-in-header", "header.html"]' …# Example of a complex TOML key.cargo --config "target.'cfg(all(target_arch = \"arm\", target_os = \"none\"))'.runner = 'my-runner'" …# Example of overriding a profile setting.cargo --config profile.dev.package.image.opt-level=3 …

Config-relative paths

Paths in config files may be absolute, relative, or a bare name without any path separators.Paths for executables without a path separator will use thePATH environment variable to search for the executable.Paths for non-executables will be relative to where the config value is defined.

In particular, rules are:

For environment variables, paths are relative to the current working directory.
For config values loaded directly from the--config KEY=VALUE option,paths are relative to the current working directory.
For config files, paths are relative to the parent directory of the directory where the config files were defined,no matter those files are from either thehierarchical probingor the--config <path> option.

Note: To maintain consistency with existing.cargo/config.toml probing behavior,it is by design that a path in a config file passed via--config <path>is also relative to two levels up from the config file itself.
To avoid unexpected results, the rule of thumb is putting your extra config filesat the same level of discovered.cargo/config.toml in your project.For instance, given a project/my/project,it is recommended to put config files under/my/project/.cargoor a new directory at the same level, such as/my/project/.config.

# Relative path examples.[target.x86_64-unknown-linux-gnu]runner = "foo"  # Searches `PATH` for `foo`.[source.vendored-sources]# Directory is relative to the parent where `.cargo/config.toml` is located.# For example, `/my/project/.cargo/config.toml` would result in `/my/project/vendor`.directory = "vendor"

Executable paths with arguments

Some Cargo commands invoke external programs, which can be configured as a pathand some number of arguments.

The value may be an array of strings like['/path/to/program', 'somearg'] ora space-separated string like'/path/to/program somearg'. If the path to theexecutable contains a space, the list form must be used.

If Cargo is passing other arguments to the program such as a path to open orrun, they will be passed after the last specified argument in the value of anoption of this format. If the specified program does not have path separators,Cargo will searchPATH for its executable.

Credentials

Configuration values with sensitive information are stored in the$CARGO_HOME/credentials.toml file. This file is automatically created and updatedbycargo login andcargo logout when using thecargo:token credential provider.

Tokens are used by some Cargo commands such ascargo publish forauthenticating with remote registries. Care should be taken to protect thetokens and to keep them secret.

It follows the same format as Cargo config files.

[registry]token = "…"   # Access token for crates.io[registries.<name>]token = "…"   # Access token for the named registry

As with most other config values, tokens may be specified with environmentvariables. The token forcrates.io may be specified with theCARGO_REGISTRY_TOKEN environment variable. Tokens for other registries maybe specified with environment variables of the formCARGO_REGISTRIES_<name>_TOKEN where<name> is the name of the registry inall capital letters.

Note: Cargo also reads and writes credential files without the.tomlextension, such as.cargo/credentials. Support for the.toml extensionwas added in version 1.39. In version 1.68, Cargo writes to the file with theextension by default. However, for backward compatibility reason, when bothfiles exist, Cargo will read and write the file without the extension.

Configuration keys

This section documents all configuration keys. The description for keys withvariable parts are annotated with angled brackets liketarget.<triple> wherethe<triple> part can be anytarget triple liketarget.x86_64-pc-windows-msvc.

`paths`

Type: array of strings (paths)
Default: none
Environment: not supported

An array of paths to local packages which are to be used as overrides fordependencies. For more information see theOverriding Dependenciesguide.

`[alias]`

Type: string or array of strings
Default: see below
Environment:CARGO_ALIAS_<name>

The[alias] table defines CLI command aliases. For example, runningcargo b is an alias for runningcargo build. Each key in the table is thesubcommand, and the value is the actual command to run. The value may be anarray of strings, where the first element is the command and the following arearguments. It may also be a string, which will be split on spaces intosubcommand and arguments. The following aliases are built-in to Cargo:

[alias]b = "build"c = "check"d = "doc"t = "test"r = "run"rm = "remove"

Aliases are not allowed to redefine existing built-in commands.

Aliases are recursive:

[alias]rr = "run --release"recursive_example = "rr --example recursions"

`[build]`

The[build] table controls build-time operations and compiler settings.

`build.jobs`

Type: integer or string
Default: number of logical CPUs
Environment:CARGO_BUILD_JOBS

Sets the maximum number of compiler processes to run in parallel. If negative,it sets the maximum number of compiler processes to the number of logical CPUsplus provided value. Should not be 0. If a stringdefault is provided, it setsthe value back to defaults.

Can be overridden with the--jobs CLI option.

`build.rustc`

Type: string (program path)
Default:"rustc"
Environment:CARGO_BUILD_RUSTC orRUSTC

Sets the executable to use forrustc.

`build.rustc-wrapper`

Type: string (program path)
Default: none
Environment:CARGO_BUILD_RUSTC_WRAPPER orRUSTC_WRAPPER

Sets a wrapper to execute instead ofrustc. The first argument passed to thewrapper is the path to the actual executable to use(i.e.,build.rustc, if that is set, or"rustc" otherwise).

`build.rustc-workspace-wrapper`

Type: string (program path)
Default: none
Environment:CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER orRUSTC_WORKSPACE_WRAPPER

Sets a wrapper to execute instead ofrustc, for workspace members only. When building asingle-package project without workspaces, that package is considered to be the workspace. The firstargument passed to the wrapper is the path to the actual executable to use (i.e.,build.rustc, ifthat is set, or"rustc" otherwise). It affects the filename hash so that artifacts produced by thewrapper are cached separately.

If bothrustc-wrapper andrustc-workspace-wrapper are set, then they will be nested:the final invocation is$RUSTC_WRAPPER $RUSTC_WORKSPACE_WRAPPER $RUSTC.

`build.rustdoc`

Type: string (program path)
Default:"rustdoc"
Environment:CARGO_BUILD_RUSTDOC orRUSTDOC

Sets the executable to use forrustdoc.

`build.target`

Type: string or array of strings
Default: host platform
Environment:CARGO_BUILD_TARGET

The defaulttarget platform triples to compile to.

Possible values:

Any supported target inrustc --print target-list.
"host-tuple", which will internally be substituted by the host’s target. This can be particularly useful if you’re cross-compiling some crates, and don’t want to specify your host’s machine as a target (for instance, anxtask in a shared project that may be worked on by many hosts).
A path to a custom target specification. SeeCustom Target Lookup Path for more information.

Can be overridden with the--target CLI option.

[build]target = ["x86_64-unknown-linux-gnu", "i686-unknown-linux-gnu"]

`build.target-dir`

Type: string (path)
Default:"target"
Environment:CARGO_BUILD_TARGET_DIR orCARGO_TARGET_DIR

The path to where all compiler output is placed. The default if not specifiedis a directory namedtarget located at the root of the workspace.

Can be overridden with the--target-dir CLI option.

For more information see thebuild cache documentation.

`build.build-dir`

Type: string (path)
Default: Defaults to the value ofbuild.target-dir
Environment:CARGO_BUILD_BUILD_DIR

The directory where intermediate build artifacts will be stored.Intermediate artifacts are produced by Rustc/Cargo during the build process.

This option supports path templating.

Available template variables:

{workspace-root} resolves to root of the current workspace.
{cargo-cache-home} resolves toCARGO_HOME
{workspace-path-hash} resolves to a hash of the manifest path

For more information see thebuild cache documentation.

`build.rustflags`

Type: string or array of strings
Default: none
Environment:CARGO_BUILD_RUSTFLAGS orCARGO_ENCODED_RUSTFLAGS orRUSTFLAGS

Extra command-line flags to pass torustc. The value may be an array ofstrings or a space-separated string.

There are four mutually exclusive sources of extra flags. They are checked inorder, with the first one being used:

CARGO_ENCODED_RUSTFLAGS environment variable.
RUSTFLAGS environment variable.
All matchingtarget.<triple>.rustflags andtarget.<cfg>.rustflagsconfig entries joined together.
build.rustflags config value.

Additional flags may also be passed with thecargo rustc command.

If the--target flag (orbuild.target) is used, then theflags will only be passed to the compiler for the target. Things being builtfor the host, such as build scripts or proc macros, will not receive the args.Without--target, the flags will be passed to all compiler invocations(including build scripts and proc macros) because dependencies are shared. Ifyou have args that you do not want to pass to build scripts or proc macros andare building for the host, pass--target with thehost triple.

It is not recommended to pass in flags that Cargo itself usually manages. Forexample, the flags driven byprofiles are best handled by setting theappropriate profile setting.

Caution: Due to the low-level nature of passing flags directly to thecompiler, this may cause a conflict with future versions of Cargo which mayissue the same or similar flags on its own which may interfere with theflags you specify. This is an area where Cargo may not always be backwardscompatible.

`build.rustdocflags`

Type: string or array of strings
Default: none
Environment:CARGO_BUILD_RUSTDOCFLAGS orCARGO_ENCODED_RUSTDOCFLAGS orRUSTDOCFLAGS

Extra command-line flags to pass torustdoc. The value may be an array ofstrings or a space-separated string.

There are four mutually exclusive sources of extra flags. They are checked inorder, with the first one being used:

CARGO_ENCODED_RUSTDOCFLAGS environment variable.
RUSTDOCFLAGS environment variable.
All matchingtarget.<triple>.rustdocflags config entries joined together.
build.rustdocflags config value.

Additional flags may also be passed with thecargo rustdoc command.

Caution: Due to the low-level nature of passing flags directly to thecompiler, this may cause a conflict with future versions of Cargo which mayissue the same or similar flags on its own which may interfere with theflags you specify. This is an area where Cargo may not always be backwardscompatible.

`build.incremental`

Type: bool
Default: from profile
Environment:CARGO_BUILD_INCREMENTAL orCARGO_INCREMENTAL

Whether or not to performincremental compilation. The default if not set isto use the value from theprofile. Otherwise this overrides the setting ofall profiles.

TheCARGO_INCREMENTAL environment variable can be set to1 to force enableincremental compilation for all profiles, or0 to disable it. This env varoverrides the config setting.

`build.dep-info-basedir`

Type: string (path)
Default: none
Environment:CARGO_BUILD_DEP_INFO_BASEDIR

Strips the given path prefix fromdepinfo file paths. This config settingis intended to convert absolute paths to relative paths for tools that requirerelative paths.

The setting itself is a config-relative path. So, for example, a value of"." would strip all paths starting with the parent directory of the.cargodirectory.

`build.pipelining`

This option is deprecated and unused. Cargo always has pipelining enabled.

`[credential-alias]`

Type: string or array of strings
Default: empty
Environment:CARGO_CREDENTIAL_ALIAS_<name>

The[credential-alias] table defines credential provider aliases.These aliases can be referenced as an element of theregistry.global-credential-providersarray, or as a credential provider for a specific registryunderregistries.<NAME>.credential-provider.

If specified as a string, the value will be split on spaces into path and arguments.

For example, to define an alias calledmy-alias:

[credential-alias]my-alias = ["/usr/bin/cargo-credential-example", "--argument", "value", "--flag"]

SeeRegistry Authentication for more information.

`[doc]`

The[doc] table defines options for thecargo doc command.

`doc.browser`

Type: string or array of strings (program path with args)
Default:BROWSER environment variable, or, if that is missing,opening the link in a system specific way

This option sets the browser to be used bycargo doc, overriding theBROWSER environment variable when opening documentation with the--openoption.

`[cargo-new]`

The[cargo-new] table defines defaults for thecargo new command.

`cargo-new.name`

This option is deprecated and unused.

`cargo-new.email`

This option is deprecated and unused.

`cargo-new.vcs`

Type: string
Default:"git" or"none"
Environment:CARGO_CARGO_NEW_VCS

Specifies the source control system to use for initializing a new repository.Valid values aregit,hg (for Mercurial),pijul,fossil ornone todisable this behavior. Defaults togit, ornone if already inside a VCSrepository. Can be overridden with the--vcs CLI option.

`[env]`

The[env] section allows you to set additional environment variables forbuild scripts, rustc invocations,cargo run andcargo build.

[env]OPENSSL_DIR = "/opt/openssl"

By default, the variables specified will not override values that already existin the environment. This behavior can be changed by setting theforce flag.

Setting therelative flag evaluates the value as a config-relative path thatis relative to the parent directory of the.cargo directory that contains theconfig.toml file. The value of the environment variable will be the fullabsolute path.

[env]TMPDIR = { value = "/home/tmp", force = true }OPENSSL_DIR = { value = "vendor/openssl", relative = true }

`[future-incompat-report]`

The[future-incompat-report] table controls setting forfuture incompat reporting

`future-incompat-report.frequency`

Type: string
Default:"always"
Environment:CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCY

Controls how often we display a notification to the terminal when a future incompat report is available. Possible values:

always (default): Always display a notification when a command (e.g.cargo build) produces a future incompat report
never: Never display a notification

`[cache]`

The[cache] table defines settings for cargo’s caches.

Global caches

When runningcargo commands, Cargo will automatically track which files you are using within the global cache.Periodically, Cargo will delete files that have not been used for some period of time.It will delete files that have to be downloaded from the network if they have not been used in 3 months. Files that can be generated without network access will be deleted if they have not been used in 1 month.

The automatic deletion of files only occurs when running commands that are already doing a significant amount of work, such as all of the build commands (cargo build,cargo test,cargo check, etc.), andcargo fetch.

Automatic deletion is disabled if cargo is offline such as with--offline or--frozen to avoid deleting artifacts that may need to be used if you are offline for a long period of time.

Note: This tracking is currently only implemented for the global cache in Cargo’s home directory.This includes registry indexes and source files downloaded from registries and git dependencies.Support for tracking build artifacts is not yet implemented, and tracked incargo#13136.
Additionally, there is an unstable feature to supportmanually triggering cache cleaning, and to further customize the configuration options.See theUnstable chapter for more information.

`cache.auto-clean-frequency`

Type: string
Default:"1 day"
Environment:CARGO_CACHE_AUTO_CLEAN_FREQUENCY

This option defines how often Cargo will automatically delete unused files in the global cache.This doesnot define how old the files must be, those thresholds are describedabove.

It supports the following settings:

"never" — Never deletes old files.
"always" — Checks to delete old files every time Cargo runs.
An integer followed by “seconds”, “minutes”, “hours”, “days”, “weeks”, or “months” — Checks to delete old files at most the given time frame.

`[http]`

The[http] table defines settings for HTTP behavior. This includes fetchingcrate dependencies and accessing remote git repositories.

`http.debug`

Type: boolean
Default: false
Environment:CARGO_HTTP_DEBUG

Iftrue, enables debugging of HTTP requests. The debug information can beseen by setting theCARGO_LOG=network=debug environmentvariable (or usenetwork=trace for even more information).

Be wary when posting logs from this output in a public location. The outputmay include headers with authentication tokens which you don’t want to leak!Be sure to review logs before posting them.

`http.proxy`

Type: string
Default: none
Environment:CARGO_HTTP_PROXY orHTTPS_PROXY orhttps_proxy orhttp_proxy

Sets an HTTP and HTTPS proxy to use. The format is inlibcurl format as in[protocol://]host[:port]. If not set, Cargo will also check thehttp.proxysetting in your global git configuration. If none of those are set, theHTTPS_PROXY orhttps_proxy environment variables set the proxy for HTTPSrequests, andhttp_proxy sets it for HTTP requests.

`http.timeout`

Type: integer
Default: 30
Environment:CARGO_HTTP_TIMEOUT orHTTP_TIMEOUT

Sets the timeout for each HTTP request, in seconds.

`http.cainfo`

Type: string (path)
Default: none
Environment:CARGO_HTTP_CAINFO

Path to a Certificate Authority (CA) bundle file, used to verify TLScertificates. If not specified, Cargo attempts to use the system certificates.

`http.proxy-cainfo`

Type: string (path)
Default: falls back tohttp.cainfo if not set
Environment:CARGO_HTTP_PROXY_CAINFO

Path to a Certificate Authority (CA) bundle file, used to verify proxy TLScertificates.

`http.check-revoke`

Type: boolean
Default: true (Windows) false (all others)
Environment:CARGO_HTTP_CHECK_REVOKE

This determines whether or not TLS certificate revocation checks should beperformed. This only works on Windows.

`http.ssl-version`

Type: string or min/max table
Default: none
Environment:CARGO_HTTP_SSL_VERSION

This sets the minimum TLS version to use. It takes a string, with one of thepossible values of"default","tlsv1","tlsv1.0","tlsv1.1","tlsv1.2", or"tlsv1.3".

This may alternatively take a table with two keys,min andmax, which eachtake a string value of the same kind that specifies the minimum and maximumrange of TLS versions to use.

The default is a minimum version of"tlsv1.0" and a max of the newest versionsupported on your platform, typically"tlsv1.3".

`http.low-speed-limit`

Type: integer
Default: 10
Environment:CARGO_HTTP_LOW_SPEED_LIMIT

This setting controls timeout behavior for slow connections. If the averagetransfer speed in bytes per second is below the given value forhttp.timeout seconds (default 30 seconds), then theconnection is considered too slow and Cargo will abort and retry.

`http.multiplexing`

Type: boolean
Default: true
Environment:CARGO_HTTP_MULTIPLEXING

Whentrue, Cargo will attempt to use the HTTP2 protocol with multiplexing.This allows multiple requests to use the same connection, usually improvingperformance when fetching multiple files. Iffalse, Cargo will use HTTP 1.1without pipelining.

`http.user-agent`

Type: string
Default: Cargo’s version
Environment:CARGO_HTTP_USER_AGENT

Specifies a custom user-agent header to use. The default if not specified is astring that includes Cargo’s version.

`[install]`

The[install] table defines defaults for thecargo install command.

`install.root`

Type: string (path)
Default: Cargo’s home directory
Environment:CARGO_INSTALL_ROOT

Sets the path to the root directory for installing executables forcargo install. Executables go into abin directory underneath the root.

To track information of installed executables, some extra files, such as.crates.toml and.crates2.json, are also created under this root.

The default if not specified is Cargo’s home directory (default.cargo inyour home directory).

Can be overridden with the--root command-line option.

`[net]`

The[net] table controls networking configuration.

`net.retry`

Type: integer
Default: 3
Environment:CARGO_NET_RETRY

Number of times to retry possibly spurious network errors.

`net.git-fetch-with-cli`

Type: boolean
Default: false
Environment:CARGO_NET_GIT_FETCH_WITH_CLI

If this istrue, then Cargo will use thegit executable to fetch registryindexes and git dependencies. Iffalse, then it uses a built-ingitlibrary.

Setting this totrue can be helpful if you have special authenticationrequirements that Cargo does not support. SeeGitAuthentication for more information aboutsetting up git authentication.

`net.offline`

Type: boolean
Default: false
Environment:CARGO_NET_OFFLINE

If this istrue, then Cargo will avoid accessing the network, and attempt toproceed with locally cached data. Iffalse, Cargo will access the network asneeded, and generate an error if it encounters a network error.

Can be overridden with the--offline command-line option.

`net.ssh`

The[net.ssh] table contains settings for SSH connections.

`net.ssh.known-hosts`

Type: array of strings
Default: see description
Environment: not supported

Theknown-hosts array contains a list of SSH host keys that should beaccepted as valid when connecting to an SSH server (such as for SSH gitdependencies). Each entry should be a string in a format similar to OpenSSHknown_hosts files. Each string should start with one or more hostnamesseparated by commas, a space, the key type name, a space, and thebase64-encoded key. For example:

[net.ssh]known-hosts = [    "example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFO4Q5T0UV0SQevair9PFwoxY9dl4pQl3u5phoqJH3cF"]

Cargo will attempt to load known hosts keys from common locations supported inOpenSSH, and will join those with any listed in a Cargo configuration file.If any matching entry has the correct key, the connection will be allowed.

Cargo comes with the host keys forgithub.com built-in. Ifthose ever change, you can add the new keys to the config or known_hosts file.

SeeGit Authenticationfor more details.

`[patch]`

Just as you can override dependencies using[patch] inCargo.toml, you canoverride them in the cargo configuration file to apply those patches toany affected build. The format is identical to the one used inCargo.toml.

Since.cargo/config.toml files are not usually checked into sourcecontrol, you should prefer patching usingCargo.toml where possible toensure that other developers can compile your crate in their ownenvironments. Patching through cargo configuration files is generallyonly appropriate when the patch section is automatically generated by anexternal build tool.

If a given dependency is patched both in a cargo configuration file andaCargo.toml file, the patch in the configuration file is used. Ifmultiple configuration files patch the same dependency, standard cargoconfiguration merging is used, which prefers the value defined closestto the current directory, with$HOME/.cargo/config.toml taking thelowest precedence.

Relativepath dependencies in such a[patch] section are resolvedrelative to the configuration file they appear in.

`[profile]`

The[profile] table can be used to globally change profile settings, andoverride settings specified inCargo.toml. It has the same syntax andoptions as profiles specified inCargo.toml. See theProfiles chapter fordetails about the options.

`[profile.<name>.build-override]`

Environment:CARGO_PROFILE_<name>_BUILD_OVERRIDE_<key>

The build-override table overrides settings for build scripts, proc macros,and their dependencies. It has the same keys as a normal profile. See theoverrides section for more details.

`[profile.<name>.package.<name>]`

Environment: not supported

The package table overrides settings for specific packages. It has the samekeys as a normal profile, minus thepanic,lto, andrpath settings. Seetheoverrides section for more details.

`profile.<name>.codegen-units`

Type: integer
Default: See profile docs.
Environment:CARGO_PROFILE_<name>_CODEGEN_UNITS

Seecodegen-units.

`profile.<name>.debug`

Type: integer or boolean
Default: See profile docs.
Environment:CARGO_PROFILE_<name>_DEBUG

Seedebug.

`profile.<name>.split-debuginfo`

Type: string
Default: See profile docs.
Environment:CARGO_PROFILE_<name>_SPLIT_DEBUGINFO

Seesplit-debuginfo.

`profile.<name>.debug-assertions`

Type: boolean
Default: See profile docs.
Environment:CARGO_PROFILE_<name>_DEBUG_ASSERTIONS

Seedebug-assertions.

`profile.<name>.incremental`

Type: boolean
Default: See profile docs.
Environment:CARGO_PROFILE_<name>_INCREMENTAL

Seeincremental.

`profile.<name>.lto`

Type: string or boolean
Default: See profile docs.
Environment:CARGO_PROFILE_<name>_LTO

Seelto.

`profile.<name>.overflow-checks`

Type: boolean
Default: See profile docs.
Environment:CARGO_PROFILE_<name>_OVERFLOW_CHECKS

Seeoverflow-checks.

`profile.<name>.opt-level`

Type: integer or string
Default: See profile docs.
Environment:CARGO_PROFILE_<name>_OPT_LEVEL

Seeopt-level.

`profile.<name>.panic`

Type: string
Default: See profile docs.
Environment:CARGO_PROFILE_<name>_PANIC

Seepanic.

`profile.<name>.rpath`

Type: boolean
Default: See profile docs.
Environment:CARGO_PROFILE_<name>_RPATH

Seerpath.

`profile.<name>.strip`

Type: string or boolean
Default: See profile docs.
Environment:CARGO_PROFILE_<name>_STRIP

Seestrip.

`[resolver]`

The[resolver] table overridesdependency resolution behavior for local development (e.g. excludescargo install).

`resolver.incompatible-rust-versions`

Type: string
Default: Seeresolver docs
Environment:CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS

When resolving which version of a dependency to use, select how versions with incompatiblepackage.rust-versions are treated.Values include:

allow: treatrust-version-incompatible versions like any other version
fallback: only considerrust-version-incompatible versions if no other version matched

Can be overridden with

--ignore-rust-version CLI option
Setting the dependency’s version requirement higher than any version with a compatiblerust-version
Specifying the version tocargo update with--precise

See theresolver chapter for more details.

MSRV:
allow is supported on any version
fallback is respected as of 1.84

`[registries]`

The[registries] table is used for specifying additionalregistries. Itconsists of a sub-table for each named registry.

`registries.<name>.index`

Type: string (url)
Default: none
Environment:CARGO_REGISTRIES_<name>_INDEX

Specifies the URL of the index for the registry.

`registries.<name>.token`

Type: string
Default: none
Environment:CARGO_REGISTRIES_<name>_TOKEN

Specifies the authentication token for the given registry. This value shouldonly appear in thecredentials file. This is used for registrycommands likecargo publish that require authentication.

Can be overridden with the--token command-line option.

`registries.<name>.credential-provider`

Type: string or array of path and arguments
Default: none
Environment:CARGO_REGISTRIES_<name>_CREDENTIAL_PROVIDER

Specifies the credential provider for the given registry. If not set, theproviders inregistry.global-credential-providerswill be used.

If specified as a string, path and arguments will be split on spaces. Forpaths or arguments that contain spaces, use an array.

If the value exists in the[credential-alias] table, the alias will be used.

SeeRegistry Authentication for more information.

`registries.crates-io.protocol`

Type: string
Default:"sparse"
Environment:CARGO_REGISTRIES_CRATES_IO_PROTOCOL

Specifies the protocol used to access crates.io. Allowed values aregit orsparse.

git causes Cargo to clone the entire index of all packages ever published tocrates.io fromhttps://github.com/rust-lang/crates.io-index/.This can have performance implications due to the size of the index.sparse is a newer protocol which uses HTTPS to download only what is necessary fromhttps://index.crates.io/.This can result in a significant performance improvement for resolving new dependencies in most situations.

More information about registry protocols may be found in theRegistries chapter.

`[registry]`

The[registry] table controls the default registry used when one is notspecified.

`registry.index`

This value is no longer accepted and should not be used.

`registry.default`

Type: string
Default:"crates-io"
Environment:CARGO_REGISTRY_DEFAULT

The name of the registry (from theregistries table) to useby default for registry commands likecargo publish.

Can be overridden with the--registry command-line option.

`registry.credential-provider`

Type: string or array of path and arguments
Default: none
Environment:CARGO_REGISTRY_CREDENTIAL_PROVIDER

Specifies the credential provider forcrates.io. If not set, theproviders inregistry.global-credential-providerswill be used.

If specified as a string, path and arguments will be split on spaces. Forpaths or arguments that contain spaces, use an array.

If the value exists in the[credential-alias] table, the alias will be used.

SeeRegistry Authentication for more information.

`registry.token`

Type: string
Default: none
Environment:CARGO_REGISTRY_TOKEN

Specifies the authentication token forcrates.io. This value should onlyappear in thecredentials file. This is used for registrycommands likecargo publish that require authentication.

Can be overridden with the--token command-line option.

`registry.global-credential-providers`

Type: array
Default:["cargo:token"]
Environment:CARGO_REGISTRY_GLOBAL_CREDENTIAL_PROVIDERS

Specifies the list of global credential providers. If credential provider is not setfor a specific registry usingregistries.<name>.credential-provider, Cargo will usethe credential providers in this list. Providers toward the end of the list have precedence.

Path and arguments are split on spaces. If the path or arguments contains spaces, the credentialprovider should be defined in the[credential-alias] table andreferenced here by its alias.

SeeRegistry Authentication for more information.

`[source]`

The[source] table defines the registry sources available. SeeSourceReplacement for more information. It consists of a sub-table for each namedsource. A source should only define one kind (directory, registry,local-registry, or git).

`source.<name>.replace-with`

Type: string
Default: none
Environment: not supported

If set, replace this source with the given named source or named registry.

`source.<name>.directory`

Type: string (path)
Default: none
Environment: not supported

Sets the path to a directory to use as a directory source.

`source.<name>.registry`

Type: string (url)
Default: none
Environment: not supported

Sets the URL to use for a registry source.

`source.<name>.local-registry`

Type: string (path)
Default: none
Environment: not supported

Sets the path to a directory to use as a local registry source.

`source.<name>.git`

Type: string (url)
Default: none
Environment: not supported

Sets the URL to use for a git repository source.

`source.<name>.branch`

Type: string
Default: none
Environment: not supported

Sets the branch name to use for a git repository.

If none ofbranch,tag, orrev is set, defaults to themaster branch.

`source.<name>.tag`

Type: string
Default: none
Environment: not supported

Sets the tag name to use for a git repository.

If none ofbranch,tag, orrev is set, defaults to themaster branch.

`source.<name>.rev`

Type: string
Default: none
Environment: not supported

Sets therevision to use for a git repository.

If none ofbranch,tag, orrev is set, defaults to themaster branch.

`[target]`

The[target] table is used for specifying settings for specific platformtargets. It consists of a sub-table which is either aplatform tripleor acfg() expression. The given values will be used if the target platformmatches either the<triple> value or the<cfg> expression.

[target.thumbv7m-none-eabi]linker = "arm-none-eabi-gcc"runner = "my-emulator"rustflags = ["…", "…"][target.'cfg(all(target_arch = "arm", target_os = "none"))']runner = "my-arm-wrapper"rustflags = ["…", "…"]

cfg values come from those built-in to the compiler (runrustc --print=cfgto view) and extra--cfg flags passed torustc (such as those defined inRUSTFLAGS). Do not try to match ondebug_assertions,test, Cargo featureslikefeature="foo", or values set bybuild scripts.

If using a target spec JSON file, the<triple> value is the filename stem.For example--target foo/bar.json would match[target.bar].

`target.<triple>.ar`

This option is deprecated and unused.

`target.<triple>.linker`

Type: string (program path)
Default: none
Environment:CARGO_TARGET_<triple>_LINKER

Specifies the linker which is passed torustc (via-C linker) when the<triple> is being compiled for. By default, the linker is not overridden.

`target.<cfg>.linker`

This is similar to thetarget linker, but usingacfg() expression. If both a<triple> and<cfg> runner match,the<triple> will take precedence. It is an error if more than one<cfg> runner matches the current target.

`target.<triple>.runner`

Type: string or array of strings (program path with args)
Default: none
Environment:CARGO_TARGET_<triple>_RUNNER

If a runner is provided, executables for the target<triple> will beexecuted by invoking the specified runner with the actual executable passed asan argument. This applies tocargo run,cargo test andcargo benchcommands. By default, compiled executables are executed directly.

`target.<cfg>.runner`

This is similar to thetarget runner, but usingacfg() expression. If both a<triple> and<cfg> runner match,the<triple> will take precedence. It is an error if more than one<cfg> runner matches the current target.

`target.<triple>.rustflags`

Type: string or array of strings
Default: none
Environment:CARGO_TARGET_<triple>_RUSTFLAGS

Passes a set of custom flags to the compiler for this<triple>.The value may be an array of strings or a space-separated string.

Seebuild.rustflags for more details on the differentways to specific extra flags.

`target.<cfg>.rustflags`

This is similar to thetarget rustflags, butusing acfg() expression. If several<cfg> and<triple> entriesmatch the current target, the flags are joined together.

`target.<triple>.rustdocflags`

Type: string or array of strings
Default: none
Environment:CARGO_TARGET_<triple>_RUSTDOCFLAGS

Passes a set of custom flags to the compiler for this<triple>.The value may be an array of strings or a space-separated string.

Seebuild.rustdocflags for more details on the differentways to specific extra flags.

`target.<triple>.<links>`

The links sub-table provides a way tooverride a build script. Whenspecified, the build script for the givenlinks library will not berun, and the given values will be used instead.

[target.x86_64-unknown-linux-gnu.foo]rustc-link-lib = ["foo"]rustc-link-search = ["/path/to/foo"]rustc-flags = "-L /some/path"rustc-cfg = ['key="value"']rustc-env = {key = "value"}rustc-cdylib-link-arg = ["…"]metadata_key1 = "value"metadata_key2 = "value"