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