src/doc/src/reference/config.md

   1 ## Configuration
   2
   3 This document explains how Cargo’s configuration system works, as well as
   4 available keys or configuration. For configuration of a package through its
   5 manifest, see the [manifest format](manifest.md).
   6
   7 ### Hierarchical structure
   8
   9 Cargo allows local configuration for a particular package as well as global
  10 configuration. It looks for configuration files in the current directory and
  11 all parent directories. If, for example, Cargo were invoked in
  12 `/projects/foo/bar/baz`, then the following configuration files would be
  13 probed for and unified in this order:
  14
  15 * `/projects/foo/bar/baz/.cargo/config.toml`
  16 * `/projects/foo/bar/.cargo/config.toml`
  17 * `/projects/foo/.cargo/config.toml`
  18 * `/projects/.cargo/config.toml`
  19 * `/.cargo/config.toml`
  20 * `$CARGO_HOME/config.toml` which defaults to:
  21     * Windows: `%USERPROFILE%\.cargo\config.toml`
  22     * Unix: `$HOME/.cargo/config.toml`
  23
  24 With this structure, you can specify configuration per-package, and even
  25 possibly check it into version control. You can also specify personal defaults
  26 with a configuration file in your home directory.
  27
  28 If a key is specified in multiple config files, the values will get merged
  29 together. Numbers, strings, and booleans will use the value in the deeper
  30 config directory taking precedence over ancestor directories, where the
  31 home directory is the lowest priority. Arrays will be joined together.
  32
  33 At present, when being invoked from a workspace, Cargo does not read config
  34 files from crates within the workspace. i.e. if a workspace has two crates in
  35 it, named `/projects/foo/bar/baz/mylib` and `/projects/foo/bar/baz/mybin`, and
  36 there are Cargo configs at `/projects/foo/bar/baz/mylib/.cargo/config.toml`
  37 and `/projects/foo/bar/baz/mybin/.cargo/config.toml`, Cargo does not read
  38 those configuration files if it is invoked from the workspace root
  39 (`/projects/foo/bar/baz/`).
  40
  41 > **Note:** Cargo also reads config files without the `.toml` extension, such as
  42 > `.cargo/config`. Support for the `.toml` extension was added in version 1.39
  43 > and is the preferred form. If both files exist, Cargo will use the file
  44 > without the extension.
  45
  46 ### Configuration format
  47
  48 Configuration files are written in the [TOML format][toml] (like the
  49 manifest), with simple key-value pairs inside of sections (tables). The
  50 following is a quick overview of all settings, with detailed descriptions
  51 found below.
  52
  53 ```toml
  54 paths = ["/path/to/override"] # path dependency overrides
  55
  56 [alias]     # command aliases
  57 b = "build"
  58 c = "check"
  59 t = "test"
  60 r = "run"
  61 rr = "run --release"
  62 space_example = ["run", "--release", "--", "\"command list\""]
  63
  64 [build]
  65 jobs = 1                      # number of parallel jobs, defaults to # of CPUs
  66 rustc = "rustc"               # the rust compiler tool
  67 rustc-wrapper = "…"           # run this wrapper instead of `rustc`
  68 rustc-workspace-wrapper = "…" # run this wrapper instead of `rustc` for workspace members
  69 rustdoc = "rustdoc"           # the doc generator tool
  70 target = "triple"             # build for the target triple (ignored by `cargo install`)
  71 target-dir = "target"         # path of where to place all generated artifacts
  72 rustflags = ["…", "…"]        # custom flags to pass to all compiler invocations
  73 rustdocflags = ["…", "…"]     # custom flags to pass to rustdoc
  74 incremental = true            # whether or not to enable incremental compilation
  75 dep-info-basedir = "…"        # path for the base directory for targets in depfiles
  76
  77 [doc]
  78 browser = "chromium"          # browser to use with `cargo doc --open`,
  79                               # overrides the `BROWSER` environment variable
  80
  81 [env]
  82 # Set ENV_VAR_NAME=value for any process run by Cargo
  83 ENV_VAR_NAME = "value"
  84 # Set even if already present in environment
  85 ENV_VAR_NAME_2 = { value = "value", force = true }
  86 # Value is relative to .cargo directory containing `config.toml`, make absolute
  87 ENV_VAR_NAME_3 = { value = "relative/path", relative = true }
  88
  89 [future-incompat-report]
  90 frequency = 'always' # when to display a notification about a future incompat report
  91
  92 [cargo-new]
  93 vcs = "none"              # VCS to use ('git', 'hg', 'pijul', 'fossil', 'none')
  94
  95 [http]
  96 debug = false               # HTTP debugging
  97 proxy = "host:port"         # HTTP proxy in libcurl format
  98 ssl-version = "tlsv1.3"     # TLS version to use
  99 ssl-version.max = "tlsv1.3" # maximum TLS version
 100 ssl-version.min = "tlsv1.1" # minimum TLS version
 101 timeout = 30                # timeout for each HTTP request, in seconds
 102 low-speed-limit = 10        # network timeout threshold (bytes/sec)
 103 cainfo = "cert.pem"         # path to Certificate Authority (CA) bundle
 104 check-revoke = true         # check for SSL certificate revocation
 105 multiplexing = true         # HTTP/2 multiplexing
 106 user-agent = "…"            # the user-agent header
 107
 108 [install]
 109 root = "/some/path"         # `cargo install` destination directory
 110
 111 [net]
 112 retry = 2                   # network retries
 113 git-fetch-with-cli = true   # use the `git` executable for git operations
 114 offline = true              # do not access the network
 115
 116 [patch.<registry>]
 117 # Same keys as for [patch] in Cargo.toml
 118
 119 [profile.<name>]         # Modify profile settings via config.
 120 opt-level = 0            # Optimization level.
 121 debug = true             # Include debug info.
 122 split-debuginfo = '...'  # Debug info splitting behavior.
 123 debug-assertions = true  # Enables debug assertions.
 124 overflow-checks = true   # Enables runtime integer overflow checks.
 125 lto = false              # Sets link-time optimization.
 126 panic = 'unwind'         # The panic strategy.
 127 incremental = true       # Incremental compilation.
 128 codegen-units = 16       # Number of code generation units.
 129 rpath = false            # Sets the rpath linking option.
 130 [profile.<name>.build-override]  # Overrides build-script settings.
 131 # Same keys for a normal profile.
 132 [profile.<name>.package.<name>]  # Override profile for a package.
 133 # Same keys for a normal profile (minus `panic`, `lto`, and `rpath`).
 134
 135 [registries.<name>]  # registries other than crates.io
 136 index = "…"          # URL of the registry index
 137 token = "…"          # authentication token for the registry
 138
 139 [registry]
 140 default = "…"        # name of the default registry
 141 token = "…"          # authentication token for crates.io
 142
 143 [source.<name>]      # source definition and replacement
 144 replace-with = "…"   # replace this source with the given named source
 145 directory = "…"      # path to a directory source
 146 registry = "…"       # URL to a registry source
 147 local-registry = "…" # path to a local registry source
 148 git = "…"            # URL of a git repository source
 149 branch = "…"         # branch name for the git repository
 150 tag = "…"            # tag name for the git repository
 151 rev = "…"            # revision for the git repository
 152
 153 [target.<triple>]
 154 linker = "…"            # linker to use
 155 runner = "…"            # wrapper to run executables
 156 rustflags = ["…", "…"]  # custom flags for `rustc`
 157
 158 [target.<cfg>]
 159 runner = "…"            # wrapper to run executables
 160 rustflags = ["…", "…"]  # custom flags for `rustc`
 161
 162 [target.<triple>.<links>] # `links` build script override
 163 rustc-link-lib = ["foo"]
 164 rustc-link-search = ["/path/to/foo"]
 165 rustc-flags = ["-L", "/some/path"]
 166 rustc-cfg = ['key="value"']
 167 rustc-env = {key = "value"}
 168 rustc-cdylib-link-arg = ["…"]
 169 metadata_key1 = "value"
 170 metadata_key2 = "value"
 171
 172 [term]
 173 quiet = false          # whether cargo output is quiet
 174 verbose = false        # whether cargo provides verbose output
 175 color = 'auto'         # whether cargo colorizes output
 176 progress.when = 'auto' # whether cargo shows progress bar
 177 progress.width = 80    # width of progress bar
 178 ```
 179
 180 ### Environment variables
 181
 182 Cargo can also be configured through environment variables in addition to the
 183 TOML configuration files. For each configuration key of the form `foo.bar` the
 184 environment variable `CARGO_FOO_BAR` can also be used to define the value.
 185 Keys are converted to uppercase, dots and dashes are converted to underscores.
 186 For example the `target.x86_64-unknown-linux-gnu.runner` key can also be
 187 defined by the `CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER` environment
 188 variable.
 189
 190 Environment variables will take precedence over TOML configuration files.
 191 Currently only integer, boolean, string and some array values are supported to
 192 be defined by environment variables. Descriptions below indicate which keys
 193 support environment variables.
 194
 195 In addition to the system above, Cargo recognizes a few other specific
 196 [environment variables][env].
 197
 198 ### Command-line overrides
 199
 200 Cargo also accepts arbitrary configuration overrides through the
 201 `--config` command-line option. The argument should be in TOML syntax of
 202 `KEY=VALUE`:
 203
 204 ```console
 205 cargo --config net.git-fetch-with-cli=true fetch
 206 ```
 207
 208 The `--config` option may be specified multiple times, in which case the
 209 values are merged in left-to-right order, using the same merging logic
 210 that is used when multiple configuration files apply. Configuration
 211 values specified this way take precedence over environment variables,
 212 which take precedence over configuration files.
 213
 214 Some examples of what it looks like using Bourne shell syntax:
 215
 216 ```console
 217 # Most shells will require escaping.
 218 cargo --config http.proxy=\"http://example.com\" …
 219
 220 # Spaces may be used.
 221 cargo --config "net.git-fetch-with-cli = true" …
 222
 223 # TOML array example. Single quotes make it easier to read and write.
 224 cargo --config 'build.rustdocflags = ["--html-in-header", "header.html"]' …
 225
 226 # Example of a complex TOML key.
 227 cargo --config "target.'cfg(all(target_arch = \"arm\", target_os = \"none\"))'.runner = 'my-runner'" …
 228
 229 # Example of overriding a profile setting.
 230 cargo --config profile.dev.package.image.opt-level=3 …
 231 ```
 232
 233 The `--config` option can also be used to pass paths to extra
 234 configuration files that Cargo should use for a specific invocation.
 235 Options from configuration files loaded this way follow the same
 236 precedence rules as other options specified directly with `--config`.
 237
 238 ### Config-relative paths
 239
 240 Paths in config files may be absolute, relative, or a bare name without any
 241 path separators. Paths for executables without a path separator will use the
 242 `PATH` environment variable to search for the executable. Paths for
 243 non-executables will be relative to where the config value is defined. For
 244 config files, that is relative to the parent directory of the `.cargo`
 245 directory where the value was defined. For environment variables it is
 246 relative to the current working directory.
 247
 248 ```toml
 249 # Relative path examples.
 250
 251 [target.x86_64-unknown-linux-gnu]
 252 runner = "foo"  # Searches `PATH` for `foo`.
 253
 254 [source.vendored-sources]
 255 # Directory is relative to the parent where `.cargo/config.toml` is located.
 256 # For example, `/my/project/.cargo/config.toml` would result in `/my/project/vendor`.
 257 directory = "vendor"
 258 ```
 259
 260 ### Executable paths with arguments
 261
 262 Some Cargo commands invoke external programs, which can be configured as a path
 263 and some number of arguments.
 264
 265 The value may be an array of strings like `['/path/to/program', 'somearg']` or
 266 a space-separated string like `'/path/to/program somearg'`. If the path to the
 267 executable contains a space, the list form must be used.
 268
 269 If Cargo is passing other arguments to the program such as a path to open or
 270 run, they will be passed after the last specified argument in the value of an
 271 option of this format. If the specified program does not have path separators,
 272 Cargo will search `PATH` for its executable.
 273
 274 ### Credentials
 275
 276 Configuration values with sensitive information are stored in the
 277 `$CARGO_HOME/credentials.toml` file. This file is automatically created and updated
 278 by [`cargo login`]. It follows the same format as Cargo config files.
 279
 280 ```toml
 281 [registry]
 282 token = "…"   # Access token for crates.io
 283
 284 [registries.<name>]
 285 token = "…"   # Access token for the named registry
 286 ```
 287
 288 Tokens are used by some Cargo commands such as [`cargo publish`] for
 289 authenticating with remote registries. Care should be taken to protect the
 290 tokens and to keep them secret.
 291
 292 As with most other config values, tokens may be specified with environment
 293 variables. The token for [crates.io] may be specified with the
 294 `CARGO_REGISTRY_TOKEN` environment variable. Tokens for other registries may
 295 be specified with environment variables of the form
 296 `CARGO_REGISTRIES_<name>_TOKEN` where `<name>` is the name of the registry in
 297 all capital letters.
 298
 299 ### Configuration keys
 300
 301 This section documents all configuration keys. The description for keys with
 302 variable parts are annotated with angled brackets like `target.<triple>` where
 303 the `<triple>` part can be any target triple like
 304 `target.x86_64-pc-windows-msvc`.
 305
 306 #### `paths`
 307 * Type: array of strings (paths)
 308 * Default: none
 309 * Environment: not supported
 310
 311 An array of paths to local packages which are to be used as overrides for
 312 dependencies. For more information see the [Overriding Dependencies
 313 guide](overriding-dependencies.md#paths-overrides).
 314
 315 #### `[alias]`
 316 * Type: string or array of strings
 317 * Default: see below
 318 * Environment: `CARGO_ALIAS_<name>`
 319
 320 The `[alias]` table defines CLI command aliases. For example, running `cargo
 321 b` is an alias for running `cargo build`. Each key in the table is the
 322 subcommand, and the value is the actual command to run. The value may be an
 323 array of strings, where the first element is the command and the following are
 324 arguments. It may also be a string, which will be split on spaces into
 325 subcommand and arguments. The following aliases are built-in to Cargo:
 326
 327 ```toml
 328 [alias]
 329 b = "build"
 330 c = "check"
 331 d = "doc"
 332 t = "test"
 333 r = "run"
 334 ```
 335
 336 Aliases are not allowed to redefine existing built-in commands.
 337
 338 #### `[build]`
 339
 340 The `[build]` table controls build-time operations and compiler settings.
 341
 342 ##### `build.jobs`
 343 * Type: integer
 344 * Default: number of logical CPUs
 345 * Environment: `CARGO_BUILD_JOBS`
 346
 347 Sets the maximum number of compiler processes to run in parallel. If negative,
 348 it sets the maximum number of compiler processes to the number of logical CPUs
 349 plus provided value. Should not be 0.
 350
 351 Can be overridden with the `--jobs` CLI option.
 352
 353 ##### `build.rustc`
 354 * Type: string (program path)
 355 * Default: "rustc"
 356 * Environment: `CARGO_BUILD_RUSTC` or `RUSTC`
 357
 358 Sets the executable to use for `rustc`.
 359
 360 ##### `build.rustc-wrapper`
 361 * Type: string (program path)
 362 * Default: none
 363 * Environment: `CARGO_BUILD_RUSTC_WRAPPER` or `RUSTC_WRAPPER`
 364
 365 Sets a wrapper to execute instead of `rustc`. The first argument passed to the
 366 wrapper is the path to the actual executable to use
 367 (i.e., `build.rustc`, if that is set, or `"rustc"` otherwise).
 368
 369 ##### `build.rustc-workspace-wrapper`
 370 * Type: string (program path)
 371 * Default: none
 372 * Environment: `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER` or `RUSTC_WORKSPACE_WRAPPER`
 373
 374 Sets a wrapper to execute instead of `rustc`, for workspace members only.
 375 The first argument passed to the wrapper is the path to the actual
 376 executable to use (i.e., `build.rustc`, if that is set, or `"rustc"` otherwise).
 377 It affects the filename hash so that artifacts produced by the wrapper are cached separately.
 378
 379 ##### `build.rustdoc`
 380 * Type: string (program path)
 381 * Default: "rustdoc"
 382 * Environment: `CARGO_BUILD_RUSTDOC` or `RUSTDOC`
 383
 384 Sets the executable to use for `rustdoc`.
 385
 386 ##### `build.target`
 387 * Type: string or array of strings
 388 * Default: host platform
 389 * Environment: `CARGO_BUILD_TARGET`
 390
 391 The default target platform triples to compile to.
 392
 393 This allows passing either a string or an array of strings. Each string value
 394 is a target platform triple. The selected build targets will be built for each
 395 of the selected architectures.
 396
 397 The string value may also be a relative path to a `.json` target spec file.
 398
 399 Can be overridden with the `--target` CLI option.
 400
 401 ```toml
 402 [build]
 403 target = ["x86_64-unknown-linux-gnu", "i686-unknown-linux-gnu"]
 404 ```
 405
 406 ##### `build.target-dir`
 407 * Type: string (path)
 408 * Default: "target"
 409 * Environment: `CARGO_BUILD_TARGET_DIR` or `CARGO_TARGET_DIR`
 410
 411 The path to where all compiler output is placed. The default if not specified
 412 is a directory named `target` located at the root of the workspace.
 413
 414 Can be overridden with the `--target-dir` CLI option.
 415
 416 ##### `build.rustflags`
 417 * Type: string or array of strings
 418 * Default: none
 419 * Environment: `CARGO_BUILD_RUSTFLAGS` or `CARGO_ENCODED_RUSTFLAGS` or `RUSTFLAGS`
 420
 421 Extra command-line flags to pass to `rustc`. The value may be an array of
 422 strings or a space-separated string.
 423
 424 There are four mutually exclusive sources of extra flags. They are checked in
 425 order, with the first one being used:
 426
 427 1. `CARGO_ENCODED_RUSTFLAGS` environment variable.
 428 2. `RUSTFLAGS` environment variable.
 429 3. All matching `target.<triple>.rustflags` and `target.<cfg>.rustflags`
 430    config entries joined together.
 431 4. `build.rustflags` config value.
 432
 433 Additional flags may also be passed with the [`cargo rustc`] command.
 434
 435 If the `--target` flag (or [`build.target`](#buildtarget)) is used, then the
 436 flags will only be passed to the compiler for the target. Things being built
 437 for the host, such as build scripts or proc macros, will not receive the args.
 438 Without `--target`, the flags will be passed to all compiler invocations
 439 (including build scripts and proc macros) because dependencies are shared. If
 440 you have args that you do not want to pass to build scripts or proc macros and
 441 are building for the host, pass `--target` with the host triple.
 442
 443 It is not recommended to pass in flags that Cargo itself usually manages. For
 444 example, the flags driven by [profiles](profiles.md) are best handled by setting the
 445 appropriate profile setting.
 446
 447 > **Caution**: Due to the low-level nature of passing flags directly to the
 448 > compiler, this may cause a conflict with future versions of Cargo which may
 449 > issue the same or similar flags on its own which may interfere with the
 450 > flags you specify. This is an area where Cargo may not always be backwards
 451 > compatible.
 452
 453 ##### `build.rustdocflags`
 454 * Type: string or array of strings
 455 * Default: none
 456 * Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `CARGO_ENCODED_RUSTDOCFLAGS` or `RUSTDOCFLAGS`
 457
 458 Extra command-line flags to pass to `rustdoc`. The value may be an array of
 459 strings or a space-separated string.
 460
 461 There are three mutually exclusive sources of extra flags. They are checked in
 462 order, with the first one being used:
 463
 464 1. `CARGO_ENCODED_RUSTDOCFLAGS` environment variable.
 465 2. `RUSTDOCFLAGS` environment variable.
 466 3. `build.rustdocflags` config value.
 467
 468 Additional flags may also be passed with the [`cargo rustdoc`] command.
 469
 470 ##### `build.incremental`
 471 * Type: bool
 472 * Default: from profile
 473 * Environment: `CARGO_BUILD_INCREMENTAL` or `CARGO_INCREMENTAL`
 474
 475 Whether or not to perform [incremental compilation]. The default if not set is
 476 to use the value from the [profile](profiles.md#incremental). Otherwise this overrides the setting of
 477 all profiles.
 478
 479 The `CARGO_INCREMENTAL` environment variable can be set to `1` to force enable
 480 incremental compilation for all profiles, or `0` to disable it. This env var
 481 overrides the config setting.
 482
 483 ##### `build.dep-info-basedir`
 484 * Type: string (path)
 485 * Default: none
 486 * Environment: `CARGO_BUILD_DEP_INFO_BASEDIR`
 487
 488 Strips the given path prefix from [dep
 489 info](../guide/build-cache.md#dep-info-files) file paths. This config setting
 490 is intended to convert absolute paths to relative paths for tools that require
 491 relative paths.
 492
 493 The setting itself is a config-relative path. So, for example, a value of
 494 `"."` would strip all paths starting with the parent directory of the `.cargo`
 495 directory.
 496
 497 ##### `build.pipelining`
 498
 499 This option is deprecated and unused. Cargo always has pipelining enabled.
 500
 501 #### `[doc]`
 502
 503 The `[doc]` table defines options for the [`cargo doc`] command.
 504
 505 ##### `doc.browser`
 506
 507 * Type: string or array of strings ([program path with args])
 508 * Default: `BROWSER` environment variable, or, if that is missing,
 509   opening the link in a system specific way
 510
 511 This option sets the browser to be used by [`cargo doc`], overriding the
 512 `BROWSER` environment variable when opening documentation with the `--open`
 513 option.
 514
 515 #### `[cargo-new]`
 516
 517 The `[cargo-new]` table defines defaults for the [`cargo new`] command.
 518
 519 ##### `cargo-new.name`
 520
 521 This option is deprecated and unused.
 522
 523 ##### `cargo-new.email`
 524
 525 This option is deprecated and unused.
 526
 527 ##### `cargo-new.vcs`
 528 * Type: string
 529 * Default: "git" or "none"
 530 * Environment: `CARGO_CARGO_NEW_VCS`
 531
 532 Specifies the source control system to use for initializing a new repository.
 533 Valid values are `git`, `hg` (for Mercurial), `pijul`, `fossil` or `none` to
 534 disable this behavior. Defaults to `git`, or `none` if already inside a VCS
 535 repository. Can be overridden with the `--vcs` CLI option.
 536
 537 ### `[env]`
 538
 539 The `[env]` section allows you to set additional environment variables for
 540 build scripts, rustc invocations, `cargo run` and `cargo build`.
 541
 542 ```toml
 543 [env]
 544 OPENSSL_DIR = "/opt/openssl"
 545 ```
 546
 547 By default, the variables specified will not override values that already exist
 548 in the environment. This behavior can be changed by setting the `force` flag.
 549
 550 Setting the `relative` flag evaluates the value as a config-relative path that
 551 is relative to the parent directory of the `.cargo` directory that contains the
 552 `config.toml` file. The value of the environment variable will be the full
 553 absolute path.
 554
 555 ```toml
 556 [env]
 557 TMPDIR = { value = "/home/tmp", force = true }
 558 OPENSSL_DIR = { value = "vendor/openssl", relative = true }
 559 ```
 560
 561 ### `[future-incompat-report]`
 562
 563 The `[future-incompat-report]` table controls setting for [future incompat reporting](future-incompat-report.md)
 564
 565 #### `future-incompat-report.frequency`
 566 * Type: string
 567 * Default: "always"
 568 * Environment: `CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCY`
 569
 570 Controls how often we display a notification to the terminal when a future incompat report is available. Possible values:
 571
 572 * `always` (default): Always display a notification when a command (e.g. `cargo build`) produces a future incompat report
 573 * `never`: Never display a notification
 574
 575 #### `[http]`
 576
 577 The `[http]` table defines settings for HTTP behavior. This includes fetching
 578 crate dependencies and accessing remote git repositories.
 579
 580 ##### `http.debug`
 581 * Type: boolean
 582 * Default: false
 583 * Environment: `CARGO_HTTP_DEBUG`
 584
 585 If `true`, enables debugging of HTTP requests. The debug information can be
 586 seen by setting the `CARGO_LOG=cargo::ops::registry=debug` environment
 587 variable (or use `trace` for even more information).
 588
 589 Be wary when posting logs from this output in a public location. The output
 590 may include headers with authentication tokens which you don't want to leak!
 591 Be sure to review logs before posting them.
 592
 593 ##### `http.proxy`
 594 * Type: string
 595 * Default: none
 596 * Environment: `CARGO_HTTP_PROXY` or `HTTPS_PROXY` or `https_proxy` or `http_proxy`
 597
 598 Sets an HTTP and HTTPS proxy to use. The format is in [libcurl format] as in
 599 `[protocol://]host[:port]`. If not set, Cargo will also check the `http.proxy`
 600 setting in your global git configuration. If none of those are set, the
 601 `HTTPS_PROXY` or `https_proxy` environment variables set the proxy for HTTPS
 602 requests, and `http_proxy` sets it for HTTP requests.
 603
 604 ##### `http.timeout`
 605 * Type: integer
 606 * Default: 30
 607 * Environment: `CARGO_HTTP_TIMEOUT` or `HTTP_TIMEOUT`
 608
 609 Sets the timeout for each HTTP request, in seconds.
 610
 611 ##### `http.cainfo`
 612 * Type: string (path)
 613 * Default: none
 614 * Environment: `CARGO_HTTP_CAINFO`
 615
 616 Path to a Certificate Authority (CA) bundle file, used to verify TLS
 617 certificates. If not specified, Cargo attempts to use the system certificates.
 618
 619 ##### `http.check-revoke`
 620 * Type: boolean
 621 * Default: true (Windows) false (all others)
 622 * Environment: `CARGO_HTTP_CHECK_REVOKE`
 623
 624 This determines whether or not TLS certificate revocation checks should be
 625 performed. This only works on Windows.
 626
 627 ##### `http.ssl-version`
 628 * Type: string or min/max table
 629 * Default: none
 630 * Environment: `CARGO_HTTP_SSL_VERSION`
 631
 632 This sets the minimum TLS version to use. It takes a string, with one of the
 633 possible values of "default", "tlsv1", "tlsv1.0", "tlsv1.1", "tlsv1.2", or
 634 "tlsv1.3".
 635
 636 This may alternatively take a table with two keys, `min` and `max`, which each
 637 take a string value of the same kind that specifies the minimum and maximum
 638 range of TLS versions to use.
 639
 640 The default is a minimum version of "tlsv1.0" and a max of the newest version
 641 supported on your platform, typically "tlsv1.3".
 642
 643 ##### `http.low-speed-limit`
 644 * Type: integer
 645 * Default: 10
 646 * Environment: `CARGO_HTTP_LOW_SPEED_LIMIT`
 647
 648 This setting controls timeout behavior for slow connections. If the average
 649 transfer speed in bytes per second is below the given value for
 650 [`http.timeout`](#httptimeout) seconds (default 30 seconds), then the
 651 connection is considered too slow and Cargo will abort and retry.
 652
 653 ##### `http.multiplexing`
 654 * Type: boolean
 655 * Default: true
 656 * Environment: `CARGO_HTTP_MULTIPLEXING`
 657
 658 When `true`, Cargo will attempt to use the HTTP2 protocol with multiplexing.
 659 This allows multiple requests to use the same connection, usually improving
 660 performance when fetching multiple files. If `false`, Cargo will use HTTP 1.1
 661 without pipelining.
 662
 663 ##### `http.user-agent`
 664 * Type: string
 665 * Default: Cargo's version
 666 * Environment: `CARGO_HTTP_USER_AGENT`
 667
 668 Specifies a custom user-agent header to use. The default if not specified is a
 669 string that includes Cargo's version.
 670
 671 #### `[install]`
 672
 673 The `[install]` table defines defaults for the [`cargo install`] command.
 674
 675 ##### `install.root`
 676 * Type: string (path)
 677 * Default: Cargo's home directory
 678 * Environment: `CARGO_INSTALL_ROOT`
 679
 680 Sets the path to the root directory for installing executables for [`cargo
 681 install`]. Executables go into a `bin` directory underneath the root.
 682
 683 To track information of installed executables, some extra files, such as
 684 `.crates.toml` and `.crates2.json`, are also created under this root.
 685
 686 The default if not specified is Cargo's home directory (default `.cargo` in
 687 your home directory).
 688
 689 Can be overridden with the `--root` command-line option.
 690
 691 #### `[net]`
 692
 693 The `[net]` table controls networking configuration.
 694
 695 ##### `net.retry`
 696 * Type: integer
 697 * Default: 2
 698 * Environment: `CARGO_NET_RETRY`
 699
 700 Number of times to retry possibly spurious network errors.
 701
 702 ##### `net.git-fetch-with-cli`
 703 * Type: boolean
 704 * Default: false
 705 * Environment: `CARGO_NET_GIT_FETCH_WITH_CLI`
 706
 707 If this is `true`, then Cargo will use the `git` executable to fetch registry
 708 indexes and git dependencies. If `false`, then it uses a built-in `git`
 709 library.
 710
 711 Setting this to `true` can be helpful if you have special authentication
 712 requirements that Cargo does not support. See [Git
 713 Authentication](../appendix/git-authentication.md) for more information about
 714 setting up git authentication.
 715
 716 ##### `net.offline`
 717 * Type: boolean
 718 * Default: false
 719 * Environment: `CARGO_NET_OFFLINE`
 720
 721 If this is `true`, then Cargo will avoid accessing the network, and attempt to
 722 proceed with locally cached data. If `false`, Cargo will access the network as
 723 needed, and generate an error if it encounters a network error.
 724
 725 Can be overridden with the `--offline` command-line option.
 726
 727 #### `[patch]`
 728
 729 Just as you can override dependencies using [`[patch]` in
 730 `Cargo.toml`](overriding-dependencies.md#the-patch-section), you can
 731 override them in the cargo configuration file to apply those patches to
 732 any affected build. The format is identical to the one used in
 733 `Cargo.toml`.
 734
 735 Since `.cargo/config.toml` files are not usually checked into source
 736 control, you should prefer patching using `Cargo.toml` where possible to
 737 ensure that other developers can compile your crate in their own
 738 environments. Patching through cargo configuration files is generally
 739 only appropriate when the patch section is automatically generated by an
 740 external build tool.
 741
 742 If a given dependency is patched both in a cargo configuration file and
 743 a `Cargo.toml` file, the patch in the configuration file is used. If
 744 multiple configuration files patch the same dependency, standard cargo
 745 configuration merging is used, which prefers the value defined closest
 746 to the current directory, with `$HOME/.cargo/config.toml` taking the
 747 lowest precedence.
 748
 749 Relative `path` dependencies in such a `[patch]` section are resolved
 750 relative to the configuration file they appear in.
 751
 752 #### `[profile]`
 753
 754 The `[profile]` table can be used to globally change profile settings, and
 755 override settings specified in `Cargo.toml`. It has the same syntax and
 756 options as profiles specified in `Cargo.toml`. See the [Profiles chapter] for
 757 details about the options.
 758
 759 [Profiles chapter]: profiles.md
 760
 761 ##### `[profile.<name>.build-override]`
 762 * Environment: `CARGO_PROFILE_<name>_BUILD_OVERRIDE_<key>`
 763
 764 The build-override table overrides settings for build scripts, proc macros,
 765 and their dependencies. It has the same keys as a normal profile. See the
 766 [overrides section](profiles.md#overrides) for more details.
 767
 768 ##### `[profile.<name>.package.<name>]`
 769 * Environment: not supported
 770
 771 The package table overrides settings for specific packages. It has the same
 772 keys as a normal profile, minus the `panic`, `lto`, and `rpath` settings. See
 773 the [overrides section](profiles.md#overrides) for more details.
 774
 775 ##### `profile.<name>.codegen-units`
 776 * Type: integer
 777 * Default: See profile docs.
 778 * Environment: `CARGO_PROFILE_<name>_CODEGEN_UNITS`
 779
 780 See [codegen-units](profiles.md#codegen-units).
 781
 782 ##### `profile.<name>.debug`
 783 * Type: integer or boolean
 784 * Default: See profile docs.
 785 * Environment: `CARGO_PROFILE_<name>_DEBUG`
 786
 787 See [debug](profiles.md#debug).
 788
 789 ##### `profile.<name>.split-debuginfo`
 790 * Type: string
 791 * Default: See profile docs.
 792 * Environment: `CARGO_PROFILE_<name>_SPLIT_DEBUGINFO`
 793
 794 See [split-debuginfo](profiles.md#split-debuginfo).
 795
 796 ##### `profile.<name>.debug-assertions`
 797 * Type: boolean
 798 * Default: See profile docs.
 799 * Environment: `CARGO_PROFILE_<name>_DEBUG_ASSERTIONS`
 800
 801 See [debug-assertions](profiles.md#debug-assertions).
 802
 803 ##### `profile.<name>.incremental`
 804 * Type: boolean
 805 * Default: See profile docs.
 806 * Environment: `CARGO_PROFILE_<name>_INCREMENTAL`
 807
 808 See [incremental](profiles.md#incremental).
 809
 810 ##### `profile.<name>.lto`
 811 * Type: string or boolean
 812 * Default: See profile docs.
 813 * Environment: `CARGO_PROFILE_<name>_LTO`
 814
 815 See [lto](profiles.md#lto).
 816
 817 ##### `profile.<name>.overflow-checks`
 818 * Type: boolean
 819 * Default: See profile docs.
 820 * Environment: `CARGO_PROFILE_<name>_OVERFLOW_CHECKS`
 821
 822 See [overflow-checks](profiles.md#overflow-checks).
 823
 824 ##### `profile.<name>.opt-level`
 825 * Type: integer or string
 826 * Default: See profile docs.
 827 * Environment: `CARGO_PROFILE_<name>_OPT_LEVEL`
 828
 829 See [opt-level](profiles.md#opt-level).
 830
 831 ##### `profile.<name>.panic`
 832 * Type: string
 833 * default: See profile docs.
 834 * Environment: `CARGO_PROFILE_<name>_PANIC`
 835
 836 See [panic](profiles.md#panic).
 837
 838 ##### `profile.<name>.rpath`
 839 * Type: boolean
 840 * default: See profile docs.
 841 * Environment: `CARGO_PROFILE_<name>_RPATH`
 842
 843 See [rpath](profiles.md#rpath).
 844
 845
 846 #### `[registries]`
 847
 848 The `[registries]` table is used for specifying additional [registries]. It
 849 consists of a sub-table for each named registry.
 850
 851 ##### `registries.<name>.index`
 852 * Type: string (url)
 853 * Default: none
 854 * Environment: `CARGO_REGISTRIES_<name>_INDEX`
 855
 856 Specifies the URL of the git index for the registry.
 857
 858 ##### `registries.<name>.token`
 859 * Type: string
 860 * Default: none
 861 * Environment: `CARGO_REGISTRIES_<name>_TOKEN`
 862
 863 Specifies the authentication token for the given registry. This value should
 864 only appear in the [credentials](#credentials) file. This is used for registry
 865 commands like [`cargo publish`] that require authentication.
 866
 867 Can be overridden with the `--token` command-line option.
 868
 869 #### `[registry]`
 870
 871 The `[registry]` table controls the default registry used when one is not
 872 specified.
 873
 874 ##### `registry.index`
 875
 876 This value is no longer accepted and should not be used.
 877
 878 ##### `registry.default`
 879 * Type: string
 880 * Default: `"crates-io"`
 881 * Environment: `CARGO_REGISTRY_DEFAULT`
 882
 883 The name of the registry (from the [`registries` table](#registries)) to use
 884 by default for registry commands like [`cargo publish`].
 885
 886 Can be overridden with the `--registry` command-line option.
 887
 888 ##### `registry.token`
 889 * Type: string
 890 * Default: none
 891 * Environment: `CARGO_REGISTRY_TOKEN`
 892
 893 Specifies the authentication token for [crates.io]. This value should only
 894 appear in the [credentials](#credentials) file. This is used for registry
 895 commands like [`cargo publish`] that require authentication.
 896
 897 Can be overridden with the `--token` command-line option.
 898
 899 #### `[source]`
 900
 901 The `[source]` table defines the registry sources available. See [Source
 902 Replacement] for more information. It consists of a sub-table for each named
 903 source. A source should only define one kind (directory, registry,
 904 local-registry, or git).
 905
 906 ##### `source.<name>.replace-with`
 907 * Type: string
 908 * Default: none
 909 * Environment: not supported
 910
 911 If set, replace this source with the given named source.
 912
 913 ##### `source.<name>.directory`
 914 * Type: string (path)
 915 * Default: none
 916 * Environment: not supported
 917
 918 Sets the path to a directory to use as a directory source.
 919
 920 ##### `source.<name>.registry`
 921 * Type: string (url)
 922 * Default: none
 923 * Environment: not supported
 924
 925 Sets the URL to use for a registry source.
 926
 927 ##### `source.<name>.local-registry`
 928 * Type: string (path)
 929 * Default: none
 930 * Environment: not supported
 931
 932 Sets the path to a directory to use as a local registry source.
 933
 934 ##### `source.<name>.git`
 935 * Type: string (url)
 936 * Default: none
 937 * Environment: not supported
 938
 939 Sets the URL to use for a git repository source.
 940
 941 ##### `source.<name>.branch`
 942 * Type: string
 943 * Default: none
 944 * Environment: not supported
 945
 946 Sets the branch name to use for a git repository.
 947
 948 If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch.
 949
 950 ##### `source.<name>.tag`
 951 * Type: string
 952 * Default: none
 953 * Environment: not supported
 954
 955 Sets the tag name to use for a git repository.
 956
 957 If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch.
 958
 959 ##### `source.<name>.rev`
 960 * Type: string
 961 * Default: none
 962 * Environment: not supported
 963
 964 Sets the [revision] to use for a git repository.
 965
 966 If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch.
 967
 968
 969 #### `[target]`
 970
 971 The `[target]` table is used for specifying settings for specific platform
 972 targets. It consists of a sub-table which is either a platform triple or a
 973 [`cfg()` expression]. The given values will be used if the target platform
 974 matches either the `<triple>` value or the `<cfg>` expression.
 975
 976 ```toml
 977 [target.thumbv7m-none-eabi]
 978 linker = "arm-none-eabi-gcc"
 979 runner = "my-emulator"
 980 rustflags = ["…", "…"]
 981
 982 [target.'cfg(all(target_arch = "arm", target_os = "none"))']
 983 runner = "my-arm-wrapper"
 984 rustflags = ["…", "…"]
 985 ```
 986
 987 `cfg` values come from those built-in to the compiler (run `rustc --print=cfg`
 988 to view), values set by [build scripts], and extra `--cfg` flags passed to
 989 `rustc` (such as those defined in `RUSTFLAGS`). Do not try to match on
 990 `debug_assertions` or Cargo features like `feature="foo"`.
 991
 992 If using a target spec JSON file, the `<triple>` value is the filename stem.
 993 For example `--target foo/bar.json` would match `[target.bar]`.
 994
 995 ##### `target.<triple>.ar`
 996
 997 This option is deprecated and unused.
 998
 999 ##### `target.<triple>.linker`
1000 * Type: string (program path)
1001 * Default: none
1002 * Environment: `CARGO_TARGET_<triple>_LINKER`
1003
1004 Specifies the linker which is passed to `rustc` (via [`-C linker`]) when the
1005 `<triple>` is being compiled for. By default, the linker is not overridden.
1006
1007 ##### `target.<triple>.runner`
1008 * Type: string or array of strings ([program path with args])
1009 * Default: none
1010 * Environment: `CARGO_TARGET_<triple>_RUNNER`
1011
1012 If a runner is provided, executables for the target `<triple>` will be
1013 executed by invoking the specified runner with the actual executable passed as
1014 an argument. This applies to [`cargo run`], [`cargo test`] and [`cargo bench`]
1015 commands. By default, compiled executables are executed directly.
1016
1017 ##### `target.<cfg>.runner`
1018
1019 This is similar to the [target runner](#targettriplerunner), but using
1020 a [`cfg()` expression]. If both a `<triple>` and `<cfg>` runner match,
1021 the `<triple>` will take precedence. It is an error if more than one
1022 `<cfg>` runner matches the current target.
1023
1024 ##### `target.<triple>.rustflags`
1025 * Type: string or array of strings
1026 * Default: none
1027 * Environment: `CARGO_TARGET_<triple>_RUSTFLAGS`
1028
1029 Passes a set of custom flags to the compiler for this `<triple>`. The value
1030 may be an array of strings or a space-separated string.
1031
1032 See [`build.rustflags`](#buildrustflags) for more details on the different
1033 ways to specific extra flags.
1034
1035 ##### `target.<cfg>.rustflags`
1036
1037 This is similar to the [target rustflags](#targettriplerustflags), but
1038 using a [`cfg()` expression]. If several `<cfg>` and `<triple>` entries
1039 match the current target, the flags are joined together.
1040
1041 ##### `target.<triple>.<links>`
1042
1043 The links sub-table provides a way to [override a build script]. When
1044 specified, the build script for the given `links` library will not be
1045 run, and the given values will be used instead.
1046
1047 ```toml
1048 [target.x86_64-unknown-linux-gnu.foo]
1049 rustc-link-lib = ["foo"]
1050 rustc-link-search = ["/path/to/foo"]
1051 rustc-flags = "-L /some/path"
1052 rustc-cfg = ['key="value"']
1053 rustc-env = {key = "value"}
1054 rustc-cdylib-link-arg = ["…"]
1055 metadata_key1 = "value"
1056 metadata_key2 = "value"
1057 ```
1058
1059 #### `[term]`
1060
1061 The `[term]` table controls terminal output and interaction.
1062
1063 ##### `term.quiet`
1064 * Type: boolean
1065 * Default: false
1066 * Environment: `CARGO_TERM_QUIET`
1067
1068 Controls whether or not log messages are displayed by Cargo.
1069
1070 Specifying the `--quiet` flag will override and force quiet output.
1071 Specifying the `--verbose` flag will override and disable quiet output.
1072
1073 ##### `term.verbose`
1074 * Type: boolean
1075 * Default: false
1076 * Environment: `CARGO_TERM_VERBOSE`
1077
1078 Controls whether or not extra detailed messages are displayed by Cargo.
1079
1080 Specifying the `--quiet` flag will override and disable verbose output.
1081 Specifying the `--verbose` flag will override and force verbose output.
1082
1083 ##### `term.color`
1084 * Type: string
1085 * Default: "auto"
1086 * Environment: `CARGO_TERM_COLOR`
1087
1088 Controls whether or not colored output is used in the terminal. Possible values:
1089
1090 * `auto` (default): Automatically detect if color support is available on the
1091   terminal.
1092 * `always`: Always display colors.
1093 * `never`: Never display colors.
1094
1095 Can be overridden with the `--color` command-line option.
1096
1097 ##### `term.progress.when`
1098 * Type: string
1099 * Default: "auto"
1100 * Environment: `CARGO_TERM_PROGRESS_WHEN`
1101
1102 Controls whether or not progress bar is shown in the terminal. Possible values:
1103
1104 * `auto` (default): Intelligently guess whether to show progress bar.
1105 * `always`: Always show progress bar.
1106 * `never`: Never show progress bar.
1107
1108 ##### `term.progress.width`
1109 * Type: integer
1110 * Default: none
1111 * Environment: `CARGO_TERM_PROGRESS_WIDTH`
1112
1113 Sets the width for progress bar.
1114
1115 [`cargo bench`]: ../commands/cargo-bench.md
1116 [`cargo login`]: ../commands/cargo-login.md
1117 [`cargo doc`]: ../commands/cargo-doc.md
1118 [`cargo new`]: ../commands/cargo-new.md
1119 [`cargo publish`]: ../commands/cargo-publish.md
1120 [`cargo run`]: ../commands/cargo-run.md
1121 [`cargo rustc`]: ../commands/cargo-rustc.md
1122 [`cargo test`]: ../commands/cargo-test.md
1123 [`cargo rustdoc`]: ../commands/cargo-rustdoc.md
1124 [`cargo install`]: ../commands/cargo-install.md
1125 [env]: environment-variables.md
1126 [`cfg()` expression]: ../../reference/conditional-compilation.html
1127 [build scripts]: build-scripts.md
1128 [`-C linker`]: ../../rustc/codegen-options/index.md#linker
1129 [override a build script]: build-scripts.md#overriding-build-scripts
1130 [toml]: https://toml.io/
1131 [incremental compilation]: profiles.md#incremental
1132 [program path with args]: #executable-paths-with-arguments
1133 [libcurl format]: https://everything.curl.dev/libcurl/proxies#proxy-types
1134 [source replacement]: source-replacement.md
1135 [revision]: https://git-scm.com/docs/gitrevisions
1136 [registries]: registries.md
1137 [crates.io]: https://crates.io/