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