Cargo's build system is evolving, and with the nightly-only -Zbuild-dir-new-layout flag, a major shift in how intermediate build artifacts are organized is underway. While the build directory layout is technically internal, countless projects depend on its structure due to missing Cargo features. To ensure a smooth transition for everyone, the team is calling for community testing. Here are seven key things you need to know about this change—what’s happening, how to test, what might break, and how to help shape the final design.
1. What Is Changing in the Build Directory Layout?
The new layout reorganizes build artifacts from grouping by content type (e.g., all fingerprints in one folder) to scoping by package name and a hash of the build unit and its inputs. For example, instead of a monolithic debug/fingerprint/ directory, you’ll see per-package subdirectories like debug/lib-[hash]/fingerprint/. This change improves cache invalidation and isolation between packages, but it rearranges paths that many tools and scripts rely on. Final artifacts (in target-dir) remain untouched—only intermediate build output is affected. Understanding this shift is the first step to preparing your workflow.
2. How to Test the New Layout
Testing is straightforward if you’re using nightly Rust (2026-03-10 or later). Run your usual commands with the -Zbuild-dir-new-layout flag: $ cargo test -Zbuild-dir-new-layout. This activates the new build directory structure for that command. Be sure to test your full pipeline: unit tests, integration tests, release builds, and any scripts that interact with the build directory. If you encounter failures, they may not stem solely from the layout change—Cargo 1.91+ also allows separating build artifacts (build-dir) from final ones (target-dir) via CARGO_BUILD_BUILD_DIR=build. Verify by running without the flag but with that environment variable set.
3. What Stays the Same (and What Doesn’t)
It’s crucial to distinguish between unchanged and altered aspects. Not changing: The layout of final artifacts in target-dir (e.g., release binaries remain in target/release/). Nesting under profiles and target tuples is also preserved. What changes: Intermediate artifacts are reorganized from a content-type structure (fingerprints, build scripts, etc., all separate) to a per-package structure with hashed directories. For example, build script outputs are now placed under build-dir/debug/lib-[hash]/build/ instead of a flat build/ folder. This means any tool that hardcodes paths like build-dir/debug/build/ will break.
4. Known Failure Mode: Inferring Binary Paths from Test Paths
One common pattern that will break is inferring a [[bin]] path from a [[test]] path. Many test frameworks assume that test artifacts live at a known location relative to binary outputs. In the new layout, this assumption is invalid. To fix it, use the CARGO_BIN_EXE_* environment variables introduced in Cargo 1.94+. For example, std::env::var_os("CARGO_BIN_EXE_MY_BIN") gives the correct path. As a fallback for older Cargo versions, you can keep the inference logic but test with the flag to ensure compatibility. Library authors should update their code accordingly.
5. Known Failure Mode: Build Scripts and Rustc Artifact Lookups
Build scripts that look up target-dir from their own binary location or from OUT_DIR may fail because paths have changed. See Issue #13663 for details. Similarly, user-requested artifacts from rustc (e.g., via --out-dir) are affected (Issue #13672). The recommended fix is to update current workarounds (like manually constructing paths) to use the new layout, or better, rely on Cargo’s official environment variables. If your build script detects a known structure, make it accept both old and new patterns.
6. Library Support Status: Which Tools Are Ready?
Several popular testing and tooling libraries have already adapted. As of publication time, fixed libraries include assert_cmd, executable-path, snapbox, and trycmd. Others still have known issues: cli_test_dir (Issue #65), compiletest_rs (Issue #309), term-transcript (Issue #269), and test_bin (Issue #13). If you use any of these, check for updates or consider contributing a fix. Tracking the status of your dependencies is essential before adopting the new layout.
7. How to Report Issues and Provide Feedback
Your real-world testing is invaluable. If you encounter problems, first verify they’re specific to the new layout (e.g., by retrying without the flag). Then, report issues on the tracking issue #16147 with clear reproduction steps. For upstream tools you rely on, file issues in their repositories with a reference to the tracking issue. The team is evaluating whether to make the new layout the default (see #16147), and community feedback will directly influence that decision. Your help can fix local problems, improve ecosystem compatibility, and shape Cargo’s future.
Testing the new build directory layout is a collaborative effort. By running your projects with -Zbuild-dir-new-layout, you’ll uncover hidden dependencies on internal structures—and help make the transition smoother for everyone. Whether it’s reporting a bug, updating a library, or just sharing your experience, every contribution counts. The final layout may still change, but with your input, it will be robust and well-tested for the entire Rust ecosystem.