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