Cargo's New Build Directory Layout: A Call for Community Testing and Feedback

The Rust Cargo team has introduced a new, nightly-only feature: -Zbuild-dir-new-layout. This flag triggers a significant reorganisation of how intermediate build artifacts are stored. While the build directory structure is considered an internal implementation detail, many tools and workflows inadvertently depend on its current layout. To ensure a smooth transition, the team is asking the community to test the new layout and report any issues.

Why This Matters

Although the layout of the build directory is officially internal, missing features in Cargo have led many projects to rely on the exact arrangement of files. The team has performed a crater run to identify breakages, but that can't cover every custom tool or integration. Community participation is essential to uncover hidden dependencies, report issues to affected projects, and help them update to the new layout or support both old and new simultaneously.

How to Test

You'll need a nightly compiler from 2026-03-10 or later. Run your test suite, release process, and any other operation that touches build-dir or target-dir with the -Zbuild-dir-new-layout flag. For example:

$ cargo test -Zbuild-dir-new-layout

Note that if you encounter failures, they may not be solely caused by the new layout. Since Cargo 1.91, you can separate intermediate build artifacts (set via CARGO_BUILD_BUILD_DIR=build) from final artifacts (still in target-dir). Verify that your workflow works with only this environment variable set before attributing issues to the layout change.

The team is evaluating whether to make the new layout the default in tracking issue #16147.

Expected Outcomes

• Fix local problems – Identify and resolve issues in your own projects.
• Report problems in upstream tools – File bugs with a reference to the tracking issue so others can benefit.
• Provide feedback – Share your experience on the tracking issue to inform the final design.

Known Failure Modes and Solutions

Inferring a binary's path from a test's path

Some tests construct the path to a binary by manipulating the path of the test executable. This will break under the new layout.

• Solution (Cargo 1.94+): Use std::env::var_os("CARGO_BIN_EXE_*").
• Fallback: Use env!("CARGO_BIN_EXE_*") with the CARGO_BIN_EXE_ environment variable.

Build scripts looking up target-dir from their binary or OUT_DIR

Build scripts sometimes derive the location of the target directory based on their own binary path or OUT_DIR. This assumption will no longer hold. See issue #13663.

• Solution: Update current workarounds to support the new layout. Use the CARGO_TARGET_DIR environment variable instead of inferring.

Looking up user‑requested artifacts from rustc

Tools that parse rustc output to locate built artifacts (e.g., binaries, libraries) may rely on the old directory structure. See issue #13672.

• Solution: Update tools to use Cargo's --message-format=json to reliably find artifacts, rather than scanning the build directory.

Library Compatibility Status

The following popular libraries have been checked. Status as of publication.

• 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 Changes and What Stays the Same

What Is Not Changing

• The layout of final artifacts inside target-dir remains unchanged.
• The nesting of build artifacts under the profile and, if specified, the target tuple (e.g., debug/ or release/) is preserved.

What Is Changing

The new layout switches from grouping artifacts by content type (e.g., build/, deps/, .fingerprint/) to scoping them by package name plus a hash of the build unit and its inputs. This makes the directory structure more predictable and scalable.

For example, the current layout (approximate) for a workspace with packages named lib and bin, each having a build script:

build-dir/
├── CACHEDIR.TAG
└── debug/
    ├── .cargo-lock
    ├── .fingerprint/
    │   ├── bin-[BUILD_SCRIPT_RUN_HASH]/
    │   ├── bin-[BUILD_SCRIPT_BIN_HASH]/
    │   ├── bin-[HASH]/
    │   ├── lib-[BUILD_SCRIPT_RUN_HASH]/
    │   ├── lib-[BUILD_SCRIPT_BIN_HASH]/
    │   └── lib-[HASH]/
    ├── build/
    │   ├── bin-[BIN_HASH]/
    │   ├── bin-[RUN_HASH]/
    │   ...

Under the new layout, all artifacts for a given package will be grouped under a directory named after the package, with hashing applied per unit. This eliminates cross‑package contamination and makes caching more robust.

Conclusion

The new build directory layout is a major internal improvement for Cargo, but it requires community validation before becoming the default. Please take a few minutes to test your projects with -Zbuild-dir-new-layout and report any problems. Your feedback will help make the transition smooth for everyone. For more details and to contribute to the discussion, visit tracking issue #16147.