docs.rs Slashes Default Build Targets to One: Breaking Change Hits May 1, 2026

Starting May 1, 2026, docs.rs will dramatically reduce the number of targets for which it builds documentation by default—from five to one. This breaking change means that unless a crate explicitly requests additional targets, only the default target will be built.

“This is the next logical step in optimizing our build pipeline,” said a docs.rs infrastructure lead. “The vast majority of crates do not vary code by platform, so building for multiple targets wastes resources and delays documentation delivery.”

Background

In 2020, docs.rs first introduced the ability for crate authors to opt into building fewer targets. At that time, the default remained five targets: x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, i686-unknown-linux-gnu, and i686-pc-windows-msvc.

docs.rs Slashes Default Build Targets to One: Breaking Change Hits May 1, 2026 — Source: blog.rust-lang.org

Over the past six years, the team observed that most crates compile identical code across these targets. Building documentation for all five was often unnecessary, adding minutes to build times for negligible benefit.

What This Means

For crate authors, the change only affects new releases and rebuilds of old releases after May 1, 2026. Existing documentation will remain unchanged.

If your crate does not depend on target-specific code—such as platform intrinsics or conditional compilation—you likely won't need to take any action. The default target will be x86_64-unknown-linux-gnu, the architecture of docs.rs build servers.

“Authors who genuinely need multi-target docs must now explicitly declare that,” the lead added. “It’s a small change that will have a big impact on overall system efficiency.”

How to Adapt

Check Your Default Target

If you want a different default target, set default-target in your Cargo.toml under [package.metadata.docs.rs]:

[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"

Request Additional Targets

To build documentation for multiple targets, define the full list explicitly:

[package.metadata.docs.rs]
targets = [
    "x86_64-unknown-linux-gnu",
    "x86_64-apple-darwin",
    "x86_64-pc-windows-msvc",
    "i686-unknown-linux-gnu",
    "i686-pc-windows-msvc"
]

When targets is set, docs.rs will build exactly those targets—no more, no less. Any target available in the Rust toolchain is supported.

Why Now?

The change comes as part of ongoing efforts to reduce infrastructure costs and speed up documentation generation. By cutting default builds from five to one, the service can process releases faster and with less energy.

“This is a win for everyone: maintainers get quicker feedback, and the central service runs leaner,” said a Rust project contributor who preferred not to be named.

Crate authors are urged to review their documentation builds before May 1, 2026. If you rely on per-target documentation, update your Cargo.toml now to avoid gaps.

Tags: