Cargo's Build Directory Restructuring: How to Test and Prepare for v2

Introduction

If you work with Rust and Cargo, you may have noticed the nightly-only -Zbuild-dir-new-layout flag. This flag introduces a reorganized build directory layout—a change that, while internal, affects many tools and workflows that peek behind the scenes. The Cargo team has performed a crater run, but real‑world testing is crucial to uncover edge cases. We need your help to test this feature and report issues so that tool maintainers can update their projects to support the new layout.

Why This Change Matters

Although the build directory layout is considered an implementation detail, many projects have come to depend on its structure because Cargo lacks certain features for fetching intermediate artifact paths. The new layout aims to improve build isolation and reproducibility by organizing artifacts per package and a hash of the build unit. This is a breaking change for any tool that manually navigates the build directory.

How to Test the New Layout

Testing is straightforward. You need a nightly toolchain dated at least 2026-03-10. Then run your regular commands—tests, releases, or any process that touches the build-dir or target-dir—with the -Zbuild-dir-new-layout flag.

$ cargo test -Zbuild-dir-new-layout
$ cargo build --release -Zbuild-dir-new-layout

If you encounter failures, note that they might not be solely due to the new layout. Since Cargo 1.91, users can separate intermediate build artifacts (build-dir) from final artifacts (still in target-dir). Verify by running with only CARGO_BUILD_BUILD_DIR=build set. The team is evaluating whether to make the new layout the default (see tracking issue #16147).

What to Do When You Find Problems

• Fix local issues by updating your own scripts or CI.
• Report upstream problems to the affected tool’s repository, mentioning the Cargo tracking issue.
• Provide feedback on the tracking issue itself.

Known Issues and How to Address Them

Inferring binary paths from test paths

Some test code guesses the path to a binary by manipulating its own path. This breaks because the new layout scopes test artifacts separately. Recommended fixes:

• Use std::env::var_os("CARGO_BIN_EXE_*") (available in Cargo 1.94+), optionally falling back to the inference for older Cargo versions.
• Use env!("CARGO_BIN_EXE_*") if your crate always builds with a recent enough Cargo.

Build scripts looking up target-dir

Build scripts that read OUT_DIR or the binary’s own path to find the target directory will break. See issue #13663. Workarounds need to be updated to handle the new directory structure.

Looking up user‑requested artifacts from rustc

Tools that parse rustc output or inspect the build directory for final artifacts may need changes. Refer to issue #13672.

Library Support Status

As of this writing, the following libraries have addressed the new layout:

• 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 maintain or use a tool that isn’t listed, please test it and submit an update.

What Stays the Same vs. What Changes

Not Changing

• The layout of final artifacts within the target-dir (e.g., release binaries).
• The nesting of build artifacts under the profile name and, if specified, the target tuple.

Changing

The current layout organizes content by type (e.g., all fingerprint files together). The new layout scopes content by package name and a hash of the build unit and its inputs. Here’s an illustrative example of the new structure for a workspace with packages lib and bin, both with build scripts:

build-dir/
├── CACHEDIR.TAG
└── debug/
    ├── .cargo-lock
    ├── .fingerprint/
    │   ├── bin-[HASH]*
    │   ├── lib-[HASH]*
    ├── build/
    │   ├── bin-[BIN_HASH]*
    │   ├── bin-[RUN_HASH]*
    │   ├── lib-[BIN_HASH]*
    │   ├── lib-[RUN_HASH]*
    └── …

This change improves build isolation but can break any code that assumes a flat type‑based directory.

Conclusion

Your testing is vital. By using -Zbuild-dir-new-layout and reporting issues, you help ensure a smooth transition for the entire Rust ecosystem. Update your tools early and give feedback on the tracking issue. Together we can make Cargo’s build system more robust.