rust-lang · Urgau · Apr 14, 2026
diff --git a/src/doc/rustdoc/src/command-line-arguments.md b/src/doc/rustdoc/src/command-line-arguments.md
@@ -183,6 +183,18 @@ affect that.
 The arguments to this flag are the same as those for the `-C` flag on rustc. Run `rustc -C help` to
 get the full list.
 
+## `--remap-path-prefix`: remap source paths in output
+
+This flag is the equivalent flag from `rustc`: `--remap-path-prefix`.
+
+```bash
+$ rustdoc src/lib.rs --remap-path-prefix="$PWD=/foo"
+```
+
+It permits remapping (as a best effort) source path prefixes in all output, including diagnostics,
+debug information, macro expansions, generated documentation, etc. It takes a value of the
+form `FROM=TO` where a path prefix equal to `FROM` is rewritten to the value `TO`.
+
 ## `--test`: run code examples as tests
 
 Using this flag looks like this:

diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md
@@ -751,14 +751,6 @@ pass `--doctest-build-arg ARG` for each argument `ARG`.
 
 This flag enables the generation of toggles to expand macros in the HTML source code pages.
 
-## `--remap-path-prefix`: Remap source code paths in output
-
-This flag is the equivalent flag from `rustc` `--remap-path-prefix`.
-
-it permits remapping source path prefixes in all output, including compiler diagnostics,
-debug information, macro expansions, etc. It takes a value of the form `FROM=TO`
-where a path prefix equal to `FROM` is rewritten to the value `TO`.
-
 ## `--remap-path-scope`: Scopes to which the source remapping should be done
 
 This flag is the equivalent flag from `rustc` `--remap-path-scope`.

diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs
@@ -456,6 +456,14 @@ fn opts() -> Vec<RustcOptGroup> {
                 By default, it is at `forbid` level.",
             "LEVEL",
         ),
+        opt(
+            Stable,
+            Multi,
+            "",
+            "remap-path-prefix",
+            "Remap source names in compiler messages",
+            "FROM=TO",
+        ),
         opt(Unstable, Opt, "", "index-page", "Markdown file to be used as index page", "PATH"),
         opt(
             Unstable,
@@ -548,14 +556,6 @@ fn opts() -> Vec<RustcOptGroup> {
             "Force all doctests to be compiled as a single binary, instead of one binary per test. If merging fails, rustdoc will emit a hard error.",
             "yes|no|auto",
         ),
-        opt(
-            Unstable,
-            Multi,
-            "",
-            "remap-path-prefix",
-            "Remap source names in compiler messages",
-            "FROM=TO",
-        ),
         opt(
             Unstable,
             Opt,

diff --git a/tests/run-make/rustdoc-default-output/output-default.stdout b/tests/run-make/rustdoc-default-output/output-default.stdout
@@ -125,6 +125,8 @@ Options:
                         Set the most restrictive lint level. More restrictive
                         lints are capped at this level. By default, it is at
                         `forbid` level.
+        --remap-path-prefix FROM=TO
+                        Remap source names in compiler messages
         --index-page PATH
                         Markdown file to be used as index page
         --enable-index-page 
@@ -158,8 +160,6 @@ Options:
                         Force all doctests to be compiled as a single binary,
                         instead of one binary per test. If merging fails,
                         rustdoc will emit a hard error.
-        --remap-path-prefix FROM=TO
-                        Remap source names in compiler messages
         --remap-path-scope [macro,diagnostics,debuginfo,coverage,object,all]
                         Defines which scopes of paths should be remapped by
                         `--remap-path-prefix`

diff --git a/tests/rustdoc-html/auxiliary/remapped-paths.rs b/tests/rustdoc-html/auxiliary/remapped-paths.rs
@@ -1,4 +1,4 @@
-//@ compile-flags:-Zunstable-options --remap-path-prefix={{src-base}}=
+//@ compile-flags:--remap-path-prefix={{src-base}}=
 
 pub struct MyStruct {
     field: u32,

diff --git a/tests/rustdoc-ui/lints/remap-path-prefix-lint.rs b/tests/rustdoc-ui/lints/remap-path-prefix-lint.rs
@@ -1,7 +1,7 @@
 // Regression test for remapped paths in rustdoc errors
 // <https://github.com/rust-lang/rust/issues/69264>.
 
-//@ compile-flags:-Z unstable-options --remap-path-prefix={{src-base}}=remapped_path
+//@ compile-flags:--remap-path-prefix={{src-base}}=remapped_path
 //@ rustc-env:RUST_BACKTRACE=0
 
 #![deny(rustdoc::invalid_html_tags)]

diff --git a/tests/rustdoc-ui/remap-path-prefix-doctest.rs b/tests/rustdoc-ui/remap-path-prefix-doctest.rs
@@ -9,7 +9,7 @@
 //@ revisions: without-scope
 
 //@ compile-flags:--test --test-args --test-threads=1
-//@ compile-flags:-Z unstable-options --remap-path-prefix={{src-base}}=remapped_path
+//@ compile-flags:--remap-path-prefix={{src-base}}=remapped_path
 
 //@[with-diag-scope] compile-flags: -Zunstable-options --remap-path-scope=diagnostics
 //@[with-macro-scope] compile-flags: -Zunstable-options --remap-path-scope=macro

diff --git a/tests/rustdoc-ui/remap-path-prefix-failed-doctest-output.rs b/tests/rustdoc-ui/remap-path-prefix-failed-doctest-output.rs
@@ -2,7 +2,7 @@
 // adapted to use that, and that normalize line can go away
 
 //@ failure-status: 101
-//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
+//@ compile-flags:--test --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
 //@ rustc-env:RUST_BACKTRACE=0
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ normalize-stdout: "exit (status|code): 101" -> "exit status: 101"

diff --git a/tests/rustdoc-ui/remap-path-prefix-invalid-doctest.rs b/tests/rustdoc-ui/remap-path-prefix-invalid-doctest.rs
@@ -2,7 +2,7 @@
 // adapted to use that, and that normalize line can go away
 
 //@ failure-status: 101
-//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
+//@ compile-flags:--test --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
 //@ rustc-env:RUST_BACKTRACE=0
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 

diff --git a/tests/rustdoc-ui/remap-path-prefix-macro-138520.rs b/tests/rustdoc-ui/remap-path-prefix-macro-138520.rs
@@ -2,7 +2,7 @@
 // when using --remap-path-prefix with macro rendering.
 // <https://github.com/rust-lang/rust/issues/138520>
 
-//@ compile-flags:-Z unstable-options --remap-path-prefix={{src-base}}=remapped_path
+//@ compile-flags:--remap-path-prefix={{src-base}}=remapped_path
 //@ rustc-env:RUST_BACKTRACE=0
 //@ build-pass
 

diff --git a/tests/rustdoc-ui/remap-path-prefix-passed-doctest-output.rs b/tests/rustdoc-ui/remap-path-prefix-passed-doctest-output.rs
@@ -4,7 +4,7 @@
 // FIXME: if/when the output of the test harness can be tested on its own, this test should be
 // adapted to use that, and that normalize line can go away
 
-//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
+//@ compile-flags:--test --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 
 // doctest passes at runtime

diff --git a/tests/rustdoc-ui/remap-path-prefix.rs b/tests/rustdoc-ui/remap-path-prefix.rs
@@ -7,11 +7,11 @@
 //@ revisions: with-diag-scope with-macro-scope with-debuginfo-scope with-doc-scope
 //@ revisions: without-scopes without-remap
 
-//@[with-diag-scope] compile-flags: -Zunstable-options --remap-path-prefix={{src-base}}=remapped
-//@[with-macro-scope] compile-flags: -Zunstable-options --remap-path-prefix={{src-base}}=remapped
-//@[with-debuginfo-scope] compile-flags: -Zunstable-options --remap-path-prefix={{src-base}}=remapped
-//@[with-doc-scope] compile-flags: -Zunstable-options --remap-path-prefix={{src-base}}=remapped
-//@[without-scopes] compile-flags: -Zunstable-options --remap-path-prefix={{src-base}}=remapped
+//@[with-diag-scope] compile-flags: --remap-path-prefix={{src-base}}=remapped
+//@[with-macro-scope] compile-flags: --remap-path-prefix={{src-base}}=remapped
+//@[with-debuginfo-scope] compile-flags: --remap-path-prefix={{src-base}}=remapped
+//@[with-doc-scope] compile-flags: --remap-path-prefix={{src-base}}=remapped
+//@[without-scopes] compile-flags: --remap-path-prefix={{src-base}}=remapped
 
 //@[with-diag-scope] compile-flags: -Zunstable-options --remap-path-scope=diagnostics
 //@[with-macro-scope] compile-flags: -Zunstable-options --remap-path-scope=macro