Understanding Cargo's New Build Directory Layout v2: A Q&A Guide

Cargo's nightly-only -Zbuild-dir-new-layout flag introduces a redesigned internal build directory structure. While the build dir layout is meant to be an implementation detail, many projects depend on its specifics due to missing Cargo features. This Q&A covers how to test the new layout, what changes, known issues, and how to help.

What is the new build dir layout v2 and why is it being introduced?

The new layout changes the organization of intermediate build artifacts from a content-type-based structure (e.g., .fingerprint/, build/) to a package-scoped structure using the package name and a hash of the build unit and its inputs. This change aims to improve isolation and correctness, especially for workspaces with multiple packages. The shift is necessary because the previous internal layout caused problems when separate packages shared build artifacts unexpectedly. Although the layout is internal, many external tools and processes rely on it, so the Cargo team is seeking community testing to ensure a smooth transition. They have performed a crater run but cannot cover every scenario, hence the call for testing with the nightly flag.

How can I test the new build dir layout?

To test, you need a Rust nightly toolchain dated at least 2026-03-10. Then run your tests, release processes, or any other operations that interact with the build directory or target directory using the -Zbuild-dir-new-layout flag. For example:

cargo test -Zbuild-dir-new-layout

If you encounter failures, they might not be caused solely by this flag. Starting with Cargo 1.91, you can separate where intermediate build artifacts are stored (build-dir) from final artifacts (still in target-dir) using the CARGO_BUILD_BUILD_DIR=build environment variable. This can help isolate issues. The default behavior for build-dir may change in the future as discussed in Cargo issue #16147.

What are the known issues or failure modes when using the new layout?

The Cargo team has identified several common failure patterns:

• Inferring binary paths from test paths: Instead of manually deducing a binary's location from a test's path, use std::env::var_os("CARGO_BIN_EXE_*") (available since Cargo 1.94+). You can keep the old inference as a fallback for older Cargo versions or use the compile-time macro env!("CARGO_BIN_EXE_*").
• Build scripts looking up target-dir: Build scripts that read their own binary path or OUT_DIR may break. See Issue #13663. Update workarounds to support both old and new layouts.
• Looking up user-requested artifacts from rustc: Tools that query artifacts from rustc may need updates. See Issue #13672. Again, adjust workarounds accordingly.

Which libraries have been updated to support the new layout?

As of the time of publishing, the support status of popular testing and build-interaction libraries is as follows:

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

What is changing and what is staying the same in the build directory?

Not changing: The layout of final artifacts within target-dir remains the same. Nesting of build artifacts under the profile and the target triple (if specified) is unchanged. The CACHEDIR.TAG file and the .cargo-lock file will still be present.

Changing: Instead of organizing by content type (e.g., .fingerprint/, build/, deps/), the new layout scopes everything by package name and a hash of the build unit and its inputs. For example, in the current layout you might see debug/build/bin-[BIN_HASH]/; in the new layout, those files will be nested under a package-specific directory with a hash. This reduces accidental sharing and improves build reproducibility.

How can I contribute feedback or report issues?

If you encounter problems while testing using -Zbuild-dir-new-layout, please do the following:

• Fix any local issues in your own projects if possible.
• Report problems in upstream tools (e.g., those listed in the library support section) with a note on the tracking issue to help others.
• Provide general feedback or observations on the tracking issue as well.

Your testing is valuable because the initial crater run cannot cover every possible project setup. By reporting issues, you help ensure the new layout becomes stable and works for the entire Rust ecosystem.

What if I see failures that might not be related to the new layout?

Failures can occur even without the new layout. To isolate the effect, you can use Cargo 1.91+'s ability to set a separate build directory via the environment variable CARGO_BUILD_BUILD_DIR=build. Run your commands with only that variable set (without the -Z flag) to see if the problem persists. If it does, the issue may be unrelated to the layout change. The Cargo team is evaluating whether to make build-dir separate by default in the future (tracking issue #16147). So any feedback you provide on these failures helps not only the layout change but also potential default changes.