Pass rustc the remap-path-prefix flag with a FROM=TO value, for example your project directory mapped to a fixed name. The compiler then rewrites that prefix in diagnostics, debug information and macro expansions. It does not change paths written by some linkers, so check the result.
What the flag does
The rustc book describes remapping as a partial, effort based feature across compiler generated output, including diagnostics, debugging information and macro expansions. It is useful for normalising build products, such as removing the current directory from paths in object files.
The value has the form FROM=TO. A path prefix equal to FROM is rewritten to TO. The replacement is purely textual. You can repeat the flag, and when several mappings match, the last matching one is applied. FROM may contain an equals sign, but TO may not.
rustc --remap-path-prefix "/home/user/project=/redacted" main.rs
Relative paths
Cargo may compile crates using relative paths such as src/main.rs. The book says rustc preserves relative paths where possible, but some inputs and outputs, such as debug information, can still contain absolute paths. Its advice is to remap both:
rustc --remap-path-prefix "src/=/redacted/src" --remap-path-prefix "/home/user/project=/redacted"
With Cargo you usually pass the flags through RUSTFLAGS or your build configuration, so every crate in the build gets the same mapping.
Scopes: choose all unless you know why not
A separate scope flag decides which kinds of path get remapped. The valid scopes are macro, diagnostics, debuginfo, coverage, object and all. The object scope covers paths in compiled executables and libraries, currently as an alias for macro, coverage and debuginfo. The default is all.
There is a catch. The book says scopes do not apply to rustc generated metadata, because the compiler needs the local paths there to stay correct. Artifacts containing metadata, such as rmeta files, rlibs, dynamic libraries and proc macros, keep the local paths unless you use the all scope. If your goal is reproducible builds including metadata, use all or omit the scope flag entirely.
What the flag cannot change
The book lists limits that matter in practice.
| Limit | What happens |
|---|---|
| Linker generated paths on Windows MSVC | The linker may embed absolute host paths in PDB files, independent of rustc |
| Apple platform linkers | OSO entries are not remapped by the compiler and need the linker option oso_prefix |
| Textual replacement | Path separators are not considered, so be careful with slashes and backslashes on Windows |
If you ship PDB files or macOS debug artifacts, test those separately from the main binary.
Verify, then standardise
- Build the crate in two different directories with the same remap settings.
- Compare the checksums of the outputs.
- If they differ, run diffoscope and look for your directory name in strings.
- Put the flags in one shared place, so a new service does not forget them.
Also check build.rs files. The Reproducible Builds docs warn that iterating a HashMap inside a build script gives an undefined order, and suggest a BTreeMap instead. See unstable ordering in builds.
Quick check
Does remapping make my Rust build reproducible?
It removes one source of variation. Compiler version, dependencies, linker behaviour and ordering still matter.
Which scope should I use for reproducible builds?
Use all, or leave the scope flag out. Narrower scopes can leave local paths in metadata.
Safeguard's SBOM and dependency scanning, generally available, can list the crates in a Cargo project. The free scan at gold.safeguard.sh/scan is a quick way to try it.
Sources
Last reviewed: 19 October 2026.
