Breaking: Cargo Unveils Build Dir Layout v2
The Cargo team has announced a critical testing phase for a redesigned build directory layout, available now in nightly builds via the -Zbuild-dir-new-layout flag. Developers are urged to test their projects immediately to identify compatibility issues before the change becomes the default.
According to Cargo team members, "While the layout of the build dir is internal-only, many projects need to rely on the unspecified details due to missing features within Cargo." This testing phase is essential to uncover tooling and process dependencies that could break under the new structure.
Background: Internal Change, Broad Impact
The current layout organizes build artifacts by content type. The new layout (v2) scopes artifacts by package name and a hash of the build unit and its inputs. This shift aims to improve caching and reproducibility but may disrupt tools that infer paths or rely on the old file structure.
Although a crater run has been performed, it does not cover every use case. The team needs community help to identify tools, scripts, and processes that depend on unspecified layout details. "We need help identifying tools and process that rely on the details, reporting issues to these projects so they can update to the new layout or support them both," the team stated.
What This Means for Developers
If you use nightly Rust (2026-03-10 or later), run your tests, release processes, and any other operations that touch build-dir or target-dir with the flag -Zbuild-dir-new-layout. Example: cargo test -Zbuild-dir-new-layout.
Note that failures may not be isolated to this flag. Since Cargo 1.91, you can separate intermediate artifacts (build-dir) from final artifacts (target-dir) using CARGO_BUILD_BUILD_DIR=build. The team is evaluating making this the default in #16147.
Known Failure Modes
- Inferring binary path from test path: Use
std::env::var_os("CARGO_BIN_EXE_*")(Cargo 1.94+) orenv!("CARGO_BIN_EXE_*")as fallback. - Build scripts looking up target-dir from binary or OUT_DIR: See Issue #13663 – update workarounds.
- Looking up user-requested artifacts from rustc: See Issue #13672 – update workarounds.
Library Support Status (as of publish time)
- assert_cmd: fixed
- cli_test_dir: Issue #65 – pending fix
- compiletest_rs: Issue #309 – pending fix
- executable-path: fixed
- snapbox: fixed
- term-transcript: Issue #269 – pending fix
- test_bin: Issue #13 – pending fix
- trycmd: fixed
What Is Not Changing
The layout of final artifacts within target-dir remains unchanged. The nesting of build artifacts under the profile and target tuple (if specified) also stays the same.
How to Test
Use at least nightly 2026-03-10. Run your standard workflows (tests, release builds, CI) with -Zbuild-dir-new-layout. Report issues on the tracking issue. The team encourages fixing local problems, reporting upstream issues, and providing feedback.