We would welcome people to try and report issues with the nightly-only cargo -Zbuild-dir-new-layout. While the layout of the build dir is internal-only, many projects need to rely on the unspecified details due to missing features within Cargo. While we've performed a crater run, that won't cover everything and we need help identifying tools and process that rely on the details, reporting issues to these projects so they can update to the new layout or support them both.
With at least nightly 2026-03-10, run your tests, release processes, and anything else that may touch build-dir/target-dir with the -Zbuild-dir-new-layout flag.
For example:
$ cargo test -Zbuild-dir-new-layout
Note: if you see failures, the problem may not be isolated to just -Zbuild-dir-new-layout. With Cargo 1.91, users can separate where to store intermediate build artifacts (build-dir) and final artifacts (still in target-dir). You can verify this by running with only CARGO_BUILD_BUILD_DIR=build set. We are evaluating changing the default for build-dir in #16147.
Outcomes may include:
Known failure modes:
[[bin]]s path from a [[test]]s path:std::env::var_os("CARGO_BIN_EXE_*") for Cargo 1.94+, maybe keeping the inference as a fallback for older Cargo versionsenv!("CARGO_BIN_EXE_*")OUT_DIR: see Issue #13663Library support status as of publish time:
The layout of final artifacts within target dir.
Nesting of build artifacts under the profile and the target tuple, if specified.
We are switching from organizing by content type to scoping the content by the package name and a hash of the build unit and its inputs.
Here is an example of the current layout, assuming you have a package named lib and a package named bin, and both have a build script:
build-dir/
├── CACHEDIR.TAG
└── debug/
├── .cargo-lock # file lock protecting access to this location
├── .fingerprint/ # build cache tracking
│ ├── 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]/* # build script binary
│ ├── bin-[RUN_HASH]/out/ # build script run OUT_DIR
│ ├── bin-[RUN_HASH]/* # build script run cache
│ ├── lib-[BIN_HASH]/* # build script binary
│ ├── lib-[RUN_HASH]/out/ # build script run OUT_DIR
│ └── lib-[RUN_HASH]/* # build script run cache
├── deps/
│ ├── bin-[HASH]* # binary and debug information
│ ├── lib-[HASH]* # library and debug information
│ └── liblib-[HASH]* # library and debug information
├── examples/ # unused in this case
└── incremental/... # managed by rustc
The proposed layout:
build-dir/
├── CACHEDIR.TAG
└── debug/
├── .cargo-lock # file lock protecting access to this location
├── build/
│ ├── bin/ # package name
│ │ ├── [BUILD_SCRIPT_BIN_HASH]/
│ │ │ ├── fingerprint/* # build cache tracking
│ │ │ └── out/* # build script binary
│ │ ├── [BUILD_SCRIPT_RUN_HASH]/
│ │ │ ├── fingerprint/* # build cache tracking
│ │ │ ├── out/* # build script run OUT_DIR
│ │ │ └── run/* # build script run cache
│ │ └── [HASH]/
│ │ ├── fingerprint/* # build cache tracking
│ │ └── out/* # binary and debug information
│ └── lib/ # package name
│ ├── [BUILD_SCRIPT_BIN_HASH]/
│ │ ├── fingerprint/* # build cache tracking
│ │ └── out/* # build script binary
│ ├── [BUILD_SCRIPT_RUN_HASH]/
│ │ ├── fingerprint/* # build cache tracking
│ │ ├── out/* # build script run OUT_DIR
│ │ └── run/* # build script run cache
│ └── [HASH]/
│ ├── fingerprint/* # build cache tracking
│ └── out/* # library and debug information
└── incremental/... # managed by rustc
For more information on these Cargo internals, see the mod layout documentation.
ranger-ross has worked tirelessly on this as a stepping stone to cross-workspace caching which will be easier when we can track each cacheable unit in a self-contained directory.
This also unblocks work on:
cargo test and rust-analyzer don't block on each otherAlong the way, we found this helps with:
deps/deps/ polluting PATH during builds on WindowsWhile the Cargo team does not officially endorse sharing a build-dir across workspaces, that last item should reduce the chance of encountering problems for those who choose to.
We will use the experience of this layout change to help guide how and when to perform any future layout changes, including:
--profile and --target directories, allowing sharing of more artifacts where possibleIn addition to narrowing scope, we did not do all of the layout changes now because some are blocked on the lock change which is blocked on this layout change.
We would also like to work to decouple projects from the unspecified details of build-dir.