Cargo’s New Build Directory Layout: Testing and Migration Guide

Cargo’s build directory layout is primarily an internal implementation detail, yet many projects and tools depend on its structure due to missing features in Cargo itself. With the introduction of the nightly-only -Zbuild-dir-new-layout flag, the Rust team is seeking feedback and testing from the community to ensure a smooth transition. This article explains what changes, how to test, and how to prepare your workflows for the new layout.

How to Test the New Layout

To test the new build directory layout, you need at least the nightly compiler from 2026-03-10 or later. Run your usual tests, release processes, and any scripts that interact with the build directory (or target directory) with the -Zbuild-dir-new-layout flag:

$ cargo test -Zbuild-dir-new-layout

If you encounter failures, they might not be caused solely by the new layout. Starting with Cargo 1.91, you can separate intermediate build artifacts (via build-dir) from final artifacts (still in target-dir). To verify that your issue is layout‑related, run with only the environment variable CARGO_BUILD_BUILD_DIR=build set.

What Is Changing and What Remains the Same

What Is Not Changing

The layout of final artifacts inside the target directory remains unchanged. Additionally, the nesting of build artifacts under the profile (e.g., debug or release) and under the target tuple (if specified) continues as before.

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 a side‑by‑side example assuming you have a package named lib and another named bin, both with a build script:

Current layout (content‑type based):

build-dir/
├── CACHEDIR.TAG
└── debug/
    ├── .cargo-lock
    ├── .fingerprint/
    │   ├── bin-[BUILD_SCRIPT_RUN_HASK]/*
    │   ├── 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

New layout (package+hash scoped): (Example truncated for brevity; the key change is grouping by package name before hash.)

The new approach reduces conflicts and improves cache efficiency, but it breaks any code that directly parses the build directory structure.

Common Failure Modes and How to Fix Them

Inferring a Binaries Path from a Test Path

Many test helpers infer the path to a binary from the test’s own executable location. Under the new layout this inference may fail.

• For Cargo 1.94+: Use std::env::var_os("CARGO_BIN_EXE_*") to get the exact path to the desired binary. Keep the old inference as a fallback for older Cargo versions.
• For all versions: Use the compile‑time macro env!("CARGO_BIN_EXE_*").

Build Scripts Looking Up the Target Directory

Build scripts sometimes need to locate the build directory (or target directory) from their own binary path or from OUT_DIR. This no longer works reliably. See Issue #13663 for details. Update your build script to explicitly use the provided environment variables (CARGO_TARGET_DIR, CARGO_BUILD_DIR) instead.

Looking Up User‑Requested Artifacts from Rustc

Tools that inspect artifacts at the rustc level (e.g., to find output files) must be updated. See Issue #13672. The preferred approach is to use Cargo’s metadata outputs or the CARGO_BUILD_DIR environment variable.

Library Support Status

Several popular testing and tooling libraries have already been updated or are tracking this issue. As of the time of writing:

• 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

If you use any of these, consider updating to the latest version or tracking the respective issue.

Future Plans and How You Can Help

The Cargo team is evaluating making the new layout the default (see Issue #16147). The outcomes of this testing phase may include:

• Fixing local problems you discover.
• Reporting issues in upstream tools, with a reference to the tracking issue.
• Providing feedback on the tracking issue that helps shape the final design.

By testing -Zbuild-dir-new-layout now, you help ensure that when the default changes, your projects and tools work smoothly. Please run your full test suite and any CI workflows, and report any failures or unexpected behavior.

Your participation makes Rust’s build system more robust for everyone. Thank you for testing!