Welcome to our guide on the upcoming changes to Cargo's build directory layout. This Q&A covers everything you need to know about the v2 layout, how to test it, potential pitfalls, and what stays the same. Dive in to get clear, actionable insights.
What is the new Cargo build directory layout v2?
The new layout shifts from organizing build artifacts by content type (like .fingerprint, build, deps) to grouping them by package name and a hash of the build unit and its inputs. Instead of a flat structure under build-dir/debug/, you'll see subdirectories named after each package (e.g., lib-[hash], bin-[hash]), each containing all artifacts for that package. This change improves caching and reduces conflicts, but it may break tools that rely on the old internal layout.
How can I test the new build directory layout?
You need a nightly Rust toolchain dated at least 2026-03-10. Then, run your usual build, test, or release commands with the -Zbuild-dir-new-layout flag. For example:
$ cargo test -Zbuild-dir-new-layoutYou can also separate where intermediate and final artifacts go using CARGO_BUILD_BUILD_DIR=build (available since Cargo 1.91). To isolate issues, first test without the flag, then with it. Report any failures you find, noting that the problem might not be specific to the new layout.
What are the known failure modes and how to fix them?
Three common issues have been identified:
- Inferring a binary's path from a test's path: Instead of deriving the path, use
std::env::var_os("CARGO_BIN_EXE_*")(Cargo 1.94+) or theenv!("CARGO_BIN_EXE_*")macro. You can keep old inference as a fallback 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. Again, update any workarounds.
Which tools/libraries currently support the new layout?
As of publication, here's the status for common testing and utility crates:
- 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 other tools, test them and report issues upstream.
What is not changing in the new layout?
Two important aspects remain the same:
- Final artifacts within
target dir: The location of final outputs (like binaries and libraries) is untouched. They still live undertarget/debug/ortarget/release/as before. - Nesting under profile and target tuple: If you specify a custom profile (e.g.,
--profile) or target tuple (e.g.,--target), the nesting of build artifacts under those directories is preserved.
Why is this change needed and what are the expected outcomes?
The build dir layout was always intended to be internal, but many projects have come to rely on its specific structure due to missing features in Cargo. The v2 layout improves correctness and performance, but it requires tools and processes to adapt. The community's testing can lead to:
- Fixing local problems in your own projects.
- Reporting issues in upstream tools (with a note on the tracking issue) so they can update.
- Providing feedback on the tracking issue to help us decide whether to make this the default.
What should I do if I encounter issues during testing?
If you see failures when using -Zbuild-dir-new-layout, first determine whether the issue is specific to the new layout (try running without the flag). If it is, check the tracking issue for known problems. Then:
- Fix the issue in your own project if possible.
- Report the problem to the upstream tool maintainer, linking to the tracking issue for context.
- Leave a comment on the tracking issue describing your findings to help others.
Your contribution helps make the v2 layout reliable for everyone.