Help Shape the Future of Cargo's Build Directory Layout

Cargo is experimenting with a new build directory layout, accessible via the nightly-only -Zbuild-dir-new-layout flag. While the build directory is an internal implementation detail, many tools and workflows have inadvertently come to rely on its structure. A crater run has been performed, but real‑world testing is essential to uncover hidden dependencies. This is where you come in: by testing the new layout with your projects and reporting issues, you can help ensure a smoother transition and influence its adoption as the default (tracked in #16147). Below we answer common questions about what’s changing, how to test, and known pitfalls.

What Is Changing in the Build Directory Layout?

The core change is a shift from organizing build artifacts by content type (e.g., all debug builds under debug/) to scoping them by package name plus a hash of the build unit and its inputs. In the current layout, you might see:
build-dir/debug/.fingerprint/lib-[HASH]/… and build-dir/debug/build/lib-[RUN_HASH]/…. In the new layout, artifacts are nested under a package‑specific directory (e.g., build-dir/lib-[HASH]/…). This makes caching more robust but breaks any code that assumes the old flat structure. The final artifacts in target/ are not affected.

What Is Not Changing?

The layout of final artifacts inside target/ remains the same. This means binaries, libraries, and other output files that users run or deploy will still be placed under their usual profile and target‑tuple directories. The nesting of build artifacts under the profile and target tuple, if you specify one, is also preserved. Only the intermediate build cache – the build-dir (or target/ by default) – adopts the new package‑scoped structure. Tools that only look at the final artifacts, like cargo run or cargo build --release, will work without modification.

How Can I Test the New Layout?

Use a nightly toolchain dated 2026-03-10 or later. Run your usual commands (e.g., cargo test, cargo build, release processes) with the flag -Zbuild-dir-new-layout. For example: cargo test -Zbuild-dir-new-layout. If you see failures, they might not be specific to the flag – try running with only CARGO_BUILD_BUILD_DIR=build set (available since Cargo 1.91) to isolate issues. Report any problems you encounter, and please note which tool or process broke.

What Are the Known Failure Modes?

Three categories of issues have been identified:

• Inferring a binary’s path from a test’s path: Some tools compute CARGO_BIN_EXE_* from the test binary’s location. With the new layout this inference fails. The fix is to use std::env::var_os("CARGO_BIN_EXE_*") (Cargo 1.94+) or env!("CARGO_BIN_EXE_*") instead of manual path derivation.
• Build scripts looking up target-dir from their binary or OUT_DIR: See Issue #13663. Workarounds need to be updated to handle the new layout.
• Looking up user‑requested artifacts from rustc: See Issue #13672. Again, existing workarounds must be adapted.

If your tool falls into one of these patterns, please check its repository for fixes or updates.

Which Libraries Already Support the New Layout?

As of the time of this post, several testing libraries have been updated. Here’s the status:

• 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

If you rely on a library not listed, we encourage you to test it and report issues to its maintainers.

How Should I Report Issues?

If you encounter a failure, first check whether it’s reproducible without the -Zbuild-dir-new-layout flag (e.g., using CARGO_BUILD_BUILD_DIR=build). If it only occurs with the flag, the problem is likely in the tool that is depending on the old layout. Please report the issue to that tool’s issue tracker with a note linking to the Cargo tracking issue #16147 so others can track progress. You can also provide feedback directly on the tracking issue. Your help will squash edge cases and make the transition smoother for everyone. Thank you!