Cargo's Build Directory Layout v2: A Guide for Testing and Migration

Introduction

The Rust community is preparing for a significant change in how Cargo organizes intermediate build artifacts. With the nightly-only -Zbuild-dir-new-layout flag, developers can now test the proposed new layout before it becomes the default. While the build directory structure is officially internal, many projects have come to depend on its details due to missing features in Cargo. We need your help to identify tools, scripts, and workflows that rely on the current layout so they can be updated. A crater run has already been performed, but it cannot cover every scenario. This article explains how to test the new layout, what to watch out for, and what is changing—and what is staying the same.

Cargo's Build Directory Layout v2: A Guide for Testing and Migration — Source: blog.rust-lang.org

How to Test the New Layout

Testing requires at least the nightly release from 2026-03-10. Run your test suites, release processes, and any other operations that interact with the build directory (target-dir or build-dir) using the -Zbuild-dir-new-layout flag. For example:

$ cargo test -Zbuild-dir-new-layout

Note that failures may not be exclusive to the new layout. Since Cargo 1.91, you can separate intermediate build artifacts (using the CARGO_BUILD_BUILD_DIR environment variable set to build) from final artifacts (still in target-dir). This separation is part of the ongoing changes. We are evaluating whether to make the new layout the default in issue #16147.

When you encounter issues, you can help by:

Fixing local problems – adjust your own scripts or configurations.
Reporting upstream issues – file bug reports with affected tools and link to the tracking issue.
Providing feedback – comment on the tracking issue with your findings.

Known Failure Modes

Several common patterns are known to break with the new layout. Here are the main categories and how to address them.

Inferring a Binary’s Path from a Test’s Path

Some code attempts to deduce the path of a [[bin]] artifact from the path of a [[test]] artifact. This will no longer work because the new layout reorganizes paths. Instead:

Use std::env::var_os("CARGO_BIN_EXE_*") (available since Cargo 1.94) and keep the inference as a fallback for older Cargo versions.
Alternatively, use the env!("CARGO_BIN_EXE_*") macro at compile time.

Build Scripts Looking Up target-dir

Build scripts that rely on OUT_DIR or their own binary path to infer the target-dir may break. See issue #13663. Current workarounds need to be updated to support the new layout.

Looking Up User‑Requested Artifacts from rustc

Some tools query rustc for the location of requested artifacts. This pattern is affected by the layout change. See issue #13672. Again, workarounds must be revised.

Library Support Status

Several popular testing and tooling libraries have already been updated or have open issues. 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’s Changing vs. Not Changing

What Is Not Changing

The layout of final artifacts within the target directory remains the same. The nesting of build artifacts under the profile and the target tuple (if specified) is also preserved.

What Is Changing

The new layout switches from organizing artifacts by content type to scoping them by the package name and a hash of the build unit and its inputs. Here is an illustrative comparison (assuming a workspace with packages lib and bin, both with build scripts):

Current layout (simplified):

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_HA...
    ...

The new layout will change this structure to be more predictable and isolated per package. For complete details, refer to the official RFC or tracking issue.

Conclusion

We strongly encourage all developers who use Cargo’s build directory—directly or through tooling—to test the new layout with the nightly toolchain and report any issues. Your feedback is crucial for a smooth transition. For questions or to share results, please comment on tracking issue #16147.