The Cargo team has released a second-generation build directory layout (v2) for nightly testing, calling on developers to validate it before the change becomes the default. The new layout reorganizes how intermediate build artifacts are stored, moving from a content-type organization to a per-package, hashed structure.
"We need community help to uncover edge cases that our crater runs missed," said a Cargo team member. "Many projects rely on undocumented internal details, and we want to ensure a smooth transition."
Testing requires the -Zbuild-dir-new-layout flag with nightly 2026-03-10 or later. Developers can run their test suites and release pipelines with this flag to identify incompatibilities.
Background
The build directory (or target/ subfolder) currently organizes artifacts by content type (e.g., .fingerprint, build/). While internal, many tools and scripts have come to depend on this structure due to missing Cargo features.
Proposal #16147 aims to make the new layout the default, pending community feedback. A crater run has already been performed, but the team warns it does not cover all scenarios.
How to Test
To participate, run your usual commands with the additional flag:
cargo test -Zbuild-dir-new-layoutAlso test release processes, CI scripts, and any tool that interacts with build-dir or target-dir. Failure may not be isolated to the flag — users can also set CARGO_BUILD_BUILD_DIR=build (since Cargo 1.91) to separate build and target directories.
What Is Changing
The new layout scopes build artifacts by package name and a hash of the build unit and its inputs. The old content-type folders (e.g., .fingerprint, build/) are replaced with per-package directories.
What stays the same: The final artifact layout under target/debug/ or target/release/ remains unchanged. Nesting under profile and target triple (if specified) also stays.
Known Failure Modes
Several common patterns are likely to break:
- Inferring binary paths from test paths — Use
std::env::var_os("CARGO_BIN_EXE_*")(stable since Cargo 1.94) orenv!("CARGO_BIN_EXE_*")instead of path inference. - Build scripts looking up
target-dirfrom their binary orOUT_DIR— See Issue #13663. Workarounds need updating. - Looking up user-requested artifacts from
rustc— See Issue #13672. Similar workaround updates required.
Library Support Status
The following testing libraries have been checked:
- 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
What This Means
For most developers using standard Cargo workflows, the change should be transparent. However, tools that parse the build directory structure or rely on undocumented paths will need updates.
"If your project or CI queries the build directory in any way, now is the time to test," the Cargo team emphasized. Feedback should be reported on the tracking issue #16147. The team expects to evaluate the default change after sufficient community testing.
Outcomes of this call include: fixing local issues, reporting upstream problems (with a note on the tracking issue), and providing general feedback on the proposal.