We would welcome people to try and report issues with the nightly-only cargo -Zbuild-dir-new-layout. While the layout of the build dir is internal-only, many projects need to rely on the unspecified details due to missing features within Cargo. While we've performed a crater run, that won't cover everything and we need help identifying tools and process that rely on the details, reporting issues to these projects so they can update to the new layout or support them both.

How to test this?

With at least nightly 2026-03-10, run your tests, release processes, and anything else that may touch build-dir/target-dir with the -Zbuild-dir-new-layout flag.

For example:

$ cargo test -Zbuild-dir-new-layout

Note: if you see failures, the problem may not be isolated to just -Zbuild-dir-new-layout. With Cargo 1.91, users can separate where to store intermediate build artifacts (build-dir) and final artifacts (still in target-dir). You can verify this by running with only CARGO_BUILD_BUILD_DIR=build set. We are evaluating changing the default for build-dir in #16147.

Outcomes may include:

• Fixing local problems
• Reporting problems in upstream tools with a note on the the tracking issue for others
• Providing feedback on the the tracking issue

Known failure modes:

• Inferring a [[bin]]s path from a [[test]]s path:
  • Use std::env::var_os("CARGO_BIN_EXE_*") for Cargo 1.94+, maybe keeping the inference as a fallback for older Cargo versions
  • Use env!("CARGO_BIN_EXE_*")
• Build scripts looking up target-dir from their binary or OUT_DIR: see Issue #13663
  • Update current workarounds to support the new layout
• Looking up user-requested artifacts from rustc, see Issue #13672
  • Update current workarounds to support the new layout

Library support status as of publish time:

• assert_cmd: fixed
• cli_test_dir: Issue #65
• compiletest_rs: Issue #309
• executable-path: fixed
• snapbox: fixed
• term-transcript: Issue #269
• test_bin: Issue #13
• trycmd: fixed

What is not changing?

The layout of final artifacts within target dir.

Nesting of build artifacts under the profile and the target tuple, if specified.

What is changing?

We are switching from organizing by content type to scoping the content by the package name and a hash of the build unit and its inputs.

Here is an example of the current layout, assuming you have a package named lib and a package named bin, and both have a build script:

build-dir/
├── CACHEDIR.TAG
└── debug/
    ├── .cargo-lock                       # file lock protecting access to this location
    ├── .fingerprint/                     # build cache tracking
    │   ├── bin-[BUILD_SCRIPT_RUN_HASH]/*
    │   ├── bin-[BUILD_SCRIPT_BIN_HASH]/*
    │   ├── bin-[HASH]/*
    │   ├── lib-[BUILD_SCRIPT_RUN_HASH]/*
    │   ├── lib-[BUILD_SCRIPT_BIN_HASH]/*
    │   └── lib-[HASH]/*
    ├── build/
    │    ├── bin-[BIN_HASH]/*             # build script binary
    │    ├── bin-[RUN_HASH]/out/          # build script run OUT_DIR
    │    ├── bin-[RUN_HASH]/*             # build script run cache
    │    ├── lib-[BIN_HASH]/*             # build script binary
    │    ├── lib-[RUN_HASH]/out/          # build script run OUT_DIR
    │    └── lib-[RUN_HASH]/*             # build script run cache
    ├── deps/
    │   ├── bin-[HASH]*                   # binary and debug information
    │   ├── lib-[HASH]*                   # library and debug information
    │   └── liblib-[HASH]*                # library and debug information
    ├── examples/                         # unused in this case
    └── incremental/...                   # managed by rustc

The proposed layout:

build-dir/
├── CACHEDIR.TAG
└── debug/
    ├── .cargo-lock                       # file lock protecting access to this location
    ├── build/
    │   ├── bin/                          # package name
    │   │   ├── [BUILD_SCRIPT_BIN_HASH]/
    │   │   │   ├── fingerprint/*         # build cache tracking
    │   │   │   └── out/*                 # build script binary
    │   │   ├── [BUILD_SCRIPT_RUN_HASH]/
    │   │   │   ├── fingerprint/*         # build cache tracking
    │   │   │   ├── out/*                 # build script run OUT_DIR
    │   │   │   └── run/*                 # build script run cache
    │   │   └── [HASH]/
    │   │       ├── fingerprint/*         # build cache tracking
    │   │       └── out/*                 # binary and debug information
    │   └── lib/                          # package name
    │       ├── [BUILD_SCRIPT_BIN_HASH]/
    │       │   ├── fingerprint/*         # build cache tracking
    │       │   └── out/*                 # build script binary
    │       ├── [BUILD_SCRIPT_RUN_HASH]/
    │       │   ├── fingerprint/*         # build cache tracking
    │       │   ├── out/*                 # build script run OUT_DIR
    │       │   └── run/*                 # build script run cache
    │       └── [HASH]/
    │           ├── fingerprint/*         # build cache tracking
    │           └── out/*                 # library and debug information
    └── incremental/...                   # managed by rustc

For more information on these Cargo internals, see the mod layout documentation.

Why is this being done?

ranger-ross has worked tirelessly on this as a stepping stone to cross-workspace caching which will be easier when we can track each cacheable unit in a self-contained directory.

This also unblocks work on:

• Automatic cleanup of stale build units to keep disks space use constant over time
• More granular locking so cargo test and rust-analyzer don't block on each other

Along the way, we found this helps with:

• Build performance as the intermediate artifacts accumulate in deps/
• Content of deps/ polluting PATH during builds on Windows
• Avoiding file collisions among intermediate artifacts

While the Cargo team does not officially endorse sharing a build-dir across workspaces, that last item should reduce the chance of encountering problems for those who choose to.

Future work

We will use the experience of this layout change to help guide how and when to perform any future layout changes, including:

• Efforts to reduce path lengths to reduce risks for errors for developers on Windows
• Experimenting with moving artifacts out of the --profile and --target directories, allowing sharing of more artifacts where possible

In addition to narrowing scope, we did not do all of the layout changes now because some are blocked on the lock change which is blocked on this layout change.

We would also like to work to decouple projects from the unspecified details of build-dir.