Breaking: Cargo 1.91+ Testing for -Zbuild-dir-new-layout Now Live
The Rust team has released a nightly-only flag, -Zbuild-dir-new-layout, for testing a revamped build directory structure. Developers are strongly encouraged to run their toolchains against this feature and report any failures.
"While the build directory is internal-only, many projects rely on its unspecified details due to missing features within Cargo," said a Cargo team representative. "We need help identifying tools and processes that depend on the current layout."
How to Test
To participate, use nightly 2026-03-10 or later and append -Zbuild-dir-new-layout to your Cargo commands. For example:
$ cargo test -Zbuild-dir-new-layoutThis flag applies to all commands that interact with the build directory or target directory, including release processes and CI pipelines.
Background
The current build directory (target/) organizes artifacts by content type (e.g., debug, release, build scripts). The new layout shifts to scoping artifacts by package name and a hash of the build unit and its inputs.
This change aims to improve build cache isolation and reduce conflicts in multi-package workspaces. However, it breaks existing assumptions made by tools that directly manipulate the directory structure.
"We performed a crater run, but that doesn't cover everything," the representative added. "We need community help to surface edge cases."
Known Failure Modes
Several patterns are known to break under the new layout:
- Inferring binary paths from test paths: Use
std::env::var_os("CARGO_BIN_EXE_*")(available since Cargo 1.94+) orenv!("CARGO_BIN_EXE_*")as a fallback. See details below. - Build scripts looking up target-dir from their binary or OUT_DIR: Refer to Issue #13663 for updated workarounds.
- Looking up user-requested artifacts from rustc: See Issue #13672 for guidance.
Inferring Binary Paths
Many tools derive the location of a binary from a test's path. With the new layout, this inference no longer works. The recommended fix uses environment variables provided by Cargo.
"For Cargo 1.94+, you can rely on CARGO_BIN_EXE_*," explained a Cargo documentation contributor. "For older versions, keep the inference as a fallback."
Library Support Status
Several popular testing utilities have already been updated or have pending fixes:
- 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
The new layout is not yet the default, but the team is evaluating a switch via issue #16147. If adopted, all Cargo users will eventually see a different directory structure in their target/ folder.
"For end users, the final artifacts (binaries, libraries) remain in the same place under target-dir," confirmed the Cargo representative. "Only intermediate build artifacts move." The nesting of artifacts under the profile and target tuple is unchanged.
To verify whether your project is affected by the layout change, run with only CARGO_BUILD_BUILD_DIR=build set (available since Cargo 1.91). If failures occur, they may stem from the same root causes as the new layout.
Expected Outcomes
The Cargo team expects community testing to produce:
- Fixes for local projects
- Reports to upstream tools with references to the tracking issue
- Feedback on the tracking issue itself
"We want to make sure nothing breaks silently," the representative concluded. "Please test early and report any issues."