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