Cargo Developers Urge Community Testing of New Build Directory Layout

By ✦ min read

Cargo's Build Directory Layout Overhaul Now Available for Community Testing

The Rust/Cargo team has announced that the nightly-only -Zbuild-dir-new-layout flag, which completely reorganizes the internal structure of Cargo's build directory, is now ready for community testing. Developers are urged to run their test suites, release processes, and any other workflow that touches build-dir or target-dir using the flag to uncover hidden dependencies and potential breakages.

Cargo Developers Urge Community Testing of New Build Directory Layout — Source: blog.rust-lang.org

"We've performed a crater run, but that alone won't catch every tool or process that relies on the current internal layout," said a Cargo team member. "We need the community's help to identify these dependencies so that project maintainers can update to support the new layout—or both layouts simultaneously."

How to Test

Testing requires at least nightly 2026-03-10. Run your usual Cargo commands (e.g., cargo test, cargo build, cargo release) with the -Zbuild-dir-new-layout flag appended. For example: cargo test -Zbuild-dir-new-layout.

Note: Failures may not be isolated to the new layout. Starting with Cargo 1.91, users can separate intermediate build artifacts (via CARGO_BUILD_BUILD_DIR=build) from final artifacts. The team is evaluating changing the default for build-dir in issue #16147.

Background: Why This Change Is Necessary

Currently, Cargo's build directory (build-dir) organizes artifacts by content type (e.g., debug/, release/). While this layout is internal and subject to change, many tools and scripts have come to depend on its exact structure due to missing features in Cargo. The new layout switches to scoping content by package name and a hash of the build unit and its inputs.

For example, the current layout looks like:
build-dir/debug/.fingerprint/lib-[HASH]/... build-dir/debug/build/lib-[HASH]/...
The new layout will be organized per package: build-dir/lib-[HASH]/..., making builds more cacheable and reproducible.

What This Means for Developers

Immediate action is needed. Projects that rely on the old layout—either directly via path lookups or indirectly through libraries—must be updated. The team has identified several known failure modes:

Inferring a binary path from a test path: Use std::env::var_os("CARGO_BIN_EXE_*") (available from Cargo 1.94+) or env!("CARGO_BIN_EXE_*"), optionally falling back to the old inference for older Cargo versions.
Build scripts looking up target-dir from their binary or OUT_DIR: See issue #13663. Update workarounds to support the new layout.
Looking up user-requested artifacts from rustc: See issue #13672. Update workarounds similarly.

Below is the library support status at the time of this announcement (post-publish updates may apply):

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

Expected Outcomes of Testing

By testing, you can:

Fix local problems in your own projects.
Report issues to upstream tools (with a note to the tracking issue for others).
Provide feedback on the tracking issue.

What Is Not Changing

The layout of final artifacts within target dir remains unchanged. Nesting of build artifacts under the profile and target tuple (if specified) stays the same.

Act Now

The Cargo team emphasizes that this is a critical community effort. Testing now will prevent widespread breakage when the layout becomes the default. For detailed instructions, see the How to Test section above. Report issues on the tracking issue and help shape the future of Cargo's build system.

Tags: