skip to content

In Cargo, where is `.cargo/config.toml` looked up, and which value wins when several config files and environment variables set the same key?

level: middleimportance: should knowfreq 28%

answer

  1. start where cargo is invoked
  2. walk up, then the Cargo home
  3. the deeper file outranks its ancestors
  4. lists join, single values replace
  5. environment, then --config, on top

basics

~10 s

Cargo reads .cargo/config.toml in the current directory and every parent, then $CARGO_HOME/config.toml. A deeper file's strings, numbers and booleans win, arrays are joined, CARGO_ environment variables beat the files, and --config beats both.

solid answer

~30 s

Discovery starts from the **current working directory**, not from the manifest: Cargo probes `.cargo/config.toml` there and in each parent, and last `$CARGO_HOME/config.toml` (by default `~/.cargo/config.toml`), which ranks lowest. Where files disagree, a string, number or boolean from the deeper directory wins, while an array such as `build.rustflags` is joined, higher-precedence entries last. Above the files sit the `CARGO_*` environment variables, such as `CARGO_BUILD_TARGET`, then `--config KEY=VALUE` on the command line, and a dedicated flag such as `--target` overrides the key outright. The classic surprise: `cargo build --manifest-path edge-agent/Cargo.toml` run from a parent directory never reads `edge-agent/.cargo/config.toml`.

go deeper

for a junior

Recall the search order: the current directory's .cargo/config.toml, each parent's, then the one in the Cargo home. Know that this file is separate from Cargo.toml.

for a middle

Explain the merge: deeper scalars win, arrays join, tables merge per key, then environment variables and --config layered on top, and a dedicated flag last.

for a senior

Diagnose settings that work locally and vanish in CI: a different working directory, --manifest-path from a parent, member configs unread from the root, or an environment variable overriding the file.

for a principal

Decide which settings the repository's config owns and which stay per-machine in the Cargo home or environment, so local and CI builds agree without anyone editing shared files.

## Where Cargo looks Cargo's configuration is hierarchical. When you run any Cargo command, it probes for config files starting at the **current working directory** and walking up to the filesystem root, then adds the user's own file. Invoked in `/work/fleet/edge-agent`, it reads, from highest to lowest priority: 1. `/work/fleet/edge-agent/.cargo/config.toml` 2. `/work/fleet/.cargo/config.toml` 3. `/work/.cargo/config.toml` 4. `/.cargo/config.toml` 5. `$CARGO_HOME/config.toml`, which is `~/.cargo/config.toml` on Unix unless `CARGO_HOME` points elsewhere. That layout lets a repository commit project settings, a parent directory hold settings shared by several checkouts, and each developer keep personal defaults in the home file. Cargo also accepts the older name `.cargo/config` without the extension, and prefers it when both exist. ## How values from several files merge Cargo does not pick one file; it **merges** them key by key: - **Strings, numbers and booleans**: the deeper directory wins, and the home file loses to every project file. - **Arrays** are joined, with entries from higher-precedence files placed later. - **Tables** merge per key, so a parent's `[target.aarch64-unknown-linux-gnu] linker` and a child's `runner` for the same triple both apply. Running cargo 1.99.1 in a child package whose parent directory and Cargo home also carry config shows each rule: ```toml # $CARGO_HOME/config.toml [build] target = "wasm32-unknown-unknown" rustflags = ["--cfg", "from_home"] # /work/.cargo/config.toml [build] rustflags = ["--cfg", "from_parent"] # /work/edge-agent/.cargo/config.toml [build] target = "aarch64-apple-darwin" rustflags = ["--cfg", "from_child"] ``` The child's `target` wins over the home file's, and rustc receives `--cfg from_home --cfg from_parent --cfg from_child`: one array, lowest priority first. ## Layers above the files | Layer | Example | Beats | |---|---|---| | Config files | `[build] target = "..."` | nothing; lowest | | Environment variables | `CARGO_BUILD_TARGET=aarch64-unknown-linux-gnu` | every config file | | `--config` on the command line | `--config 'build.target="wasm32-wasip1"'` | environment and files | | A dedicated flag | `--target wasm32-wasip1` | the key it stands for | A key `foo.bar` maps to `CARGO_FOO_BAR`, upper-cased, with dots and dashes turned into underscores. Not every key has an environment form; the `[source]` keys, for example, have none. For an array key such as `build.rustflags`, a `CARGO_BUILD_RUSTFLAGS` value or a `--config` value is appended to the file entries rather than replacing them; the separate `RUSTFLAGS` variable is another matter, and replaces configured flags entirely. A `--config` argument can also be a path to an extra TOML file, merged with the same rules. ## Putting the layers to work Each layer has a natural job, and keeping to it avoids most surprises: - **Repository config** holds what every build of the project needs: the cross-compiling target table, source replacement for vendored dependencies, shared aliases. - **The Cargo home file** holds personal preferences, such as an `[alias]` a developer likes, and loses to any project file on a single value, while its arrays are still joined in. - **Environment variables** suit CI images and machines that differ, such as a linker installed at another path. - **`--config`** suits one-off experiments that should leave no trace in any file. ## The current-directory rule and its surprises Because discovery follows the working directory, the same command can see different configuration: - `cargo build --manifest-path edge-agent/Cargo.toml` run from the parent reads the parent's `.cargo/` but **not** `edge-agent/.cargo/config.toml`. - Run from a workspace root, Cargo does not read `.cargo/config.toml` files inside the member crates, so a member's cross-compiling settings must move up to the root. - A CI step that runs Cargo from outside the repository, pointing at it with `--manifest-path`, silently drops the repository's config. - `cargo -C <dir>`, which would change the starting directory, is nightly-only in Cargo 1.99.1 and needs `-Z unstable-options`. Relative paths follow the same logic in reverse. A path written in a config file is resolved from the directory that contains `.cargo/`, so `tools/link.sh` works from any subdirectory. A path given in an environment variable or in `--config KEY=VALUE` is resolved from the current directory. ## Checking what Cargo actually used The stable way to see the result is `cargo build -v`: every rustc command line shows the `--target`, `-C linker=...` and extra flags Cargo settled on. `cargo config get`, which prints merged configuration, is unstable and refuses to run on the stable channel. When a setting seems ignored, check three things in order: 1. Which directory Cargo was started in. 2. Whether a `CARGO_*` variable in the shell or CI environment overrides the file. 3. Whether a flag on the command line replaces the key.

  • A workspace member keeps its own `.cargo/config.toml` with a linker setting. Why is it ignored when CI builds from the workspace root?
    Discovery walks up from the working directory, and Cargo does not read config files inside workspace members when it is invoked from the root. The member's file only applies when Cargo is started in that member's directory. Move the setting to the root's `.cargo/config.toml`, where every build of the workspace sees it.
  • Both `CARGO_BUILD_TARGET` and `--config 'build.target="wasm32-wasip1"'` are set. Which target does Cargo build?
    `wasm32-wasip1`. Values given with `--config` take precedence over environment variables, which take precedence over config files. Only the dedicated `--target` flag would override that value again.

  • Cargo looks for .cargo/config.toml next to Cargo.toml, wherever cargo is run from.
  • The home directory's config.toml overrides project config because it is the user's choice.
  • When two files set build.rustflags, the deeper file's array replaces the parent's.
  • Config files override CARGO_ environment variables because they are checked into the repository.
  • cargo config get is the stable way to print the merged configuration.