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

By • min read

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 <code>-Zbuild-dir-new-layout</code> flag with nightly 2026-03-10 or later. Developers can run their test suites and release pipelines with this flag to identify incompatibilities. <h2 id="background">Background</h2> The build directory (or <code>target/</code> subfolder) currently organizes artifacts by content type (e.g., <code>.fingerprint</code>, <code>build/</code>). While internal, many tools and scripts have come to depend on this structure due to missing Cargo features.<figure style="margin:20px 0"><img src="https://www.rust-lang.org/static/images/rust-social-wide.jpg" alt="Cargo's New Build Directory Layout v2 Enters Public Testing — Developers Urged to Test Nightly Feature" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: blog.rust-lang.org</figcaption></figure> Proposal <a href="#">#16147</a> 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. <h2 id="how-to-test">How to Test</h2> To participate, run your usual commands with the additional flag: <pre><code>cargo test -Zbuild-dir-new-layout</code></pre> Also test release processes, CI scripts, and any tool that interacts with <code>build-dir</code> or <code>target-dir</code>. Failure may not be isolated to the flag — users can also set <code>CARGO_BUILD_BUILD_DIR=build</code> (since Cargo 1.91) to separate build and target directories. <h2 id="what-is-changing">What Is Changing</h2> 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., <code>.fingerprint</code>, <code>build/</code>) are replaced with per-package directories. What stays the same: The final artifact layout under <code>target/debug/</code> or <code>target/release/</code> remains unchanged. Nesting under profile and target triple (if specified) also stays. <h2 id="known-failure-modes">Known Failure Modes</h2> Several common patterns are likely to break: <ul> <li>Inferring binary paths from test paths — Use <code>std::env::var_os("CARGO_BIN_EXE_*")</code> (stable since Cargo 1.94) or <code>env!("CARGO_BIN_EXE_*")</code> instead of path inference.</li> <li>Build scripts looking up <code>target-dir</code> from their binary or <code>OUT_DIR</code> — See <a href="https://github.com/rust-lang/cargo/issues/13663">Issue #13663</a>. Workarounds need updating.</li> <li>Looking up user-requested artifacts from <code>rustc</code> — See <a href="https://github.com/rust-lang/cargo/issues/13672">Issue #13672</a>. Similar workaround updates required.</li> </ul> <h2 id="library-support">Library Support Status</h2> The following testing libraries have been checked: <ul> <li>assert_cmd — fixed</li> <li>cli_test_dir — <a href="https://github.com/assert-rs/cli_test_dir/issues/65">Issue #65</a></li> <li>compiletest_rs — <a href="https://github.com/rust-lang/compiletest-rs/issues/309">Issue #309</a></li> <li>executable-path — fixed</li> <li>snapbox — fixed</li> <li>term-transcript — <a href="https://github.com/assert-rs/term-transcript/issues/269">Issue #269</a></li> <li>test_bin — <a href="https://github.com/assert-rs/test_bin/issues/13">Issue #13</a></li> <li>trycmd — fixed</li> </ul> <h2 id="what-this-means">What This Means</h2> 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 <a href="https://github.com/rust-lang/cargo/issues/16147">tracking issue #16147</a>. 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.