Configuration

This document will explain how Cargo’s configuration system works, as well asavailable keys or configuration. For configuration of a package through itsmanifest, see the manifest format.

Hierarchical structure

Cargo allows local configuration for a particular package as well as globalconfiguration, like git. Cargo extends this to a hierarchical strategy.If, for example, Cargo were invoked in /projects/foo/bar/baz, then thefollowing configuration files would be probed for and unified in this order:

  • /projects/foo/bar/baz/.cargo/config
  • /projects/foo/bar/.cargo/config
  • /projects/foo/.cargo/config
  • /projects/.cargo/config
  • /.cargo/config
  • $CARGO_HOME/config ($CARGO_HOME defaults to $HOME/.cargo)With this structure, you can specify configuration per-package, and evenpossibly check it into version control. You can also specify personal defaultswith a configuration file in your home directory.

Configuration format

All configuration is currently in the TOML format (like the manifest),with simple key-value pairs inside of sections (tables) which all get mergedtogether.

Configuration keys

All of the following keys are optional, and their defaults are listed as theirvalue unless otherwise noted.

Key values that specify a tool may be given as an absolute path, a relative pathor as a pathless tool name. Absolute paths and pathless tool names are used asgiven. Relative paths are resolved relative to the parent directory of the.cargo directory of the config file that the value resides within.

  1. # An array of paths to local repositories which are to be used as overrides for
  2. # dependencies. For more information see the Specifying Dependencies guide.
  3. paths = ["/path/to/override"]
  5. [cargo-new]
  6. # This is your name/email to place in the `authors` section of a new Cargo.toml
  7. # that is generated. If not present, then `git` will be probed, and if that is
  8. # not present then `$USER` and `$EMAIL` will be used.
  9. name = "..."
  10. email = "..."
  12. # By default `cargo new` will initialize a new Git repository. This key can
  13. # be set to change the version control system used. Valid values are `git`,
  14. # `hg` (for Mercurial), `pijul`, `fossil`, or `none` to disable this behavior.
  15. vcs = "none"
  17. # For the following sections, $triple refers to any valid target triple, not the
  18. # literal string "$triple", and it will apply whenever that target triple is
  19. # being compiled to. 'cfg(...)' refers to the Rust-like `#[cfg]` syntax for
  20. # conditional compilation.
  21. [target.$triple]
  22. # This is the linker which is passed to rustc (via `-C linker=`) when the `$triple`
  23. # is being compiled for. By default this flag is not passed to the compiler.
  24. linker = ".."
  25. # Same but for the library archiver which is passed to rustc via `-C ar=`.
  26. ar = ".."
  27. # If a runner is provided, compiled targets for the `$triple` will be executed
  28. # by invoking the specified runner executable with actual target as first argument.
  29. # This applies to `cargo run`, `cargo test` and `cargo bench` commands.
  30. # By default compiled targets are executed directly.
  31. runner = ".."
  32. # custom flags to pass to all compiler invocations that target $triple
  33. # this value overrides build.rustflags when both are present
  34. rustflags = ["..", ".."]
  36. [target.'cfg(...)']
  37. # Similar for the $triple configuration, but using the `cfg` syntax.
  38. # If several `cfg` and $triple targets are candidates, then the rustflags
  39. # are concatenated. The `cfg` syntax only applies to rustflags, and not to
  40. # linker.
  41. rustflags = ["..", ".."]
  42. # Similar for the $triple configuration, but using the `cfg` syntax.
  43. # If one or more `cfg`s, and a $triple target are candidates, then the $triple
  44. # will be used
  45. # If several `cfg` are candidates, then the build will error
  46. runner = ".."
  48. # Configuration keys related to the registry
  49. [registry]
  50. index = "..."   # URL of the registry index (defaults to the index of crates.io)
  51. default = "..." # Name of the default registry to use (can be overridden with
  52.                 # --registry)
  54. # Configuration keys for registries other than crates.io.
  55. # `$name` should be the name of the registry, which will be used for
  56. # dependencies in `Cargo.toml` files and the `--registry` command-line flag.
  57. # Registry names should only contain alphanumeric characters, `-`, or `_`.
  58. [registries.$name]
  59. index = "..."   # URL of the registry index
  61. [http]
  62. proxy = "host:port" # HTTP proxy to use for HTTP requests (defaults to none)
  63.                     # in libcurl format, e.g., "socks5h://host:port"
  64. timeout = 30        # Timeout for each HTTP request, in seconds
  65. cainfo = "cert.pem" # Path to Certificate Authority (CA) bundle (optional)
  66. check-revoke = true # Indicates whether SSL certs are checked for revocation
  67. low-speed-limit = 5 # Lower threshold for bytes/sec (10 = default, 0 = disabled)
  68. multiplexing = true # whether or not to use HTTP/2 multiplexing where possible
  70. # This setting can be used to help debug what's going on with HTTP requests made
  71. # by Cargo. When set to `true` then Cargo's normal debug logging will be filled
  72. # in with HTTP information, which you can extract with
  73. # `CARGO_LOG=cargo::ops::registry=debug` (and `trace` may print more).
  74. #
  75. # Be wary when posting these logs elsewhere though, it may be the case that a
  76. # header has an authentication token in it you don't want leaked! Be sure to
  77. # briefly review logs before posting them.
  78. debug = false
  80. [build]
  81. jobs = 1                  # number of parallel jobs, defaults to # of CPUs
  82. rustc = "rustc"           # the rust compiler tool
  83. rustdoc = "rustdoc"       # the doc generator tool
  84. target = "triple"         # build for the target triple (ignored by `cargo install`)
  85. target-dir = "target"     # path of where to place all generated artifacts
  86. rustflags = ["..", ".."]  # custom flags to pass to all compiler invocations
  87. rustdocflags = ["..", ".."]  # custom flags to pass to rustdoc
  88. incremental = true        # whether or not to enable incremental compilation
  89.                           # If `incremental` is not set, then the value from
  90.                           # the profile is used.
  91. dep-info-basedir = ".."   # full path for the base directory for targets in depfiles
  93. [term]
  94. verbose = false        # whether cargo provides verbose output
  95. color = 'auto'         # whether cargo colorizes output
  97. # Network configuration
  98. [net]
  99. retry = 2 # number of times a network call will automatically retried
  100. git-fetch-with-cli = false  # if `true` we'll use `git`-the-CLI to fetch git repos
  101. offline = false # do not access the network, but otherwise try to proceed if possible
  103. # Alias cargo commands. The first 4 aliases are built in. If your
  104. # command requires grouped whitespace use the list format.
  105. [alias]
  106. b = "build"
  107. c = "check"
  108. t = "test"
  109. r = "run"
  110. rr = "run --release"
  111. space_example = ["run", "--release", "--", "\"command list\""]

Environment variables

Cargo can also be configured through environment variables in addition to theTOML syntax above. For each configuration key above of the form foo.bar theenvironment variable CARGO_FOO_BAR can also be used to define the value. Forexample the build.jobs key can also be defined by CARGO_BUILD_JOBS.

Environment variables will take precedent over TOML configuration, and currentlyonly integer, boolean, and string keys are supported to be defined byenvironment variables. This means that source replacement, which is expressed bytables, cannot be configured through environment variables.

In addition to the system above, Cargo recognizes a few other specificenvironment variables.

Credentials

Configuration values with sensitive information are stored in the$CARGO_HOME/credentials file. This file is automatically created and updatedby cargo login. It follows the same format as Cargo config files.

  1. [registry]
  2. token = "..."   # Access token for crates.io
  4. # `$name` should be a registry name (see above for more information about
  5. # configuring registries).
  6. [registries.$name]
  7. token = "..."   # Access token for the named registry

Tokens are used by some Cargo commands such as cargo publish forauthenticating with remote registries. Care should be taken to protect thetokens and to keep them secret.

As with most other config values, tokens may be specified with environmentvariables. The token for crates.io may be specified with theCARGO_REGISTRY_TOKEN environment variable. Tokens for other registries maybe specified with environment variables of the formCARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry in allcapital letters.