Cargo's New Build Directory Layout v2 Enters Public Testing — Developers Urged to Test Nightly Feature

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-layout

Also 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) or env!("CARGO_BIN_EXE_*") instead of path inference.
• Build scripts looking up target-dir from their binary or OUT_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.