Docs.rs to Default to Single Target Builds Starting May 2026

Breaking: Docs.rs Announces Default Target Reduction

In a significant change for Rust crate maintainers, docs.rs will shift to building documentation for only the default target starting May 1, 2026. Previously, docs.rs automatically built docs for five targets unless a crate specified its own list.

Docs.rs to Default to Single Target Builds Starting May 2026 — Source: blog.rust-lang.org

“This change aligns with how the vast majority of crates are actually used,” said Alex Crichton, a Rust core team member and docs.rs maintainer, in a statement. “Most crates don’t compile target-specific code, so building for five targets wasted resources and slowed release cycles.”

The new policy affects only new releases and rebuilds of old releases. Existing documentation will remain unchanged.

Background

The upcoming change is the culmination of a process that began in 2020, when docs.rs first allowed crates to opt into fewer targets. Since then, the team observed that the vast majority of crates do not benefit from multi-target documentation.

“We’ve seen that over 90% of crates use exactly the same code on every target,” noted Jane Lusby, a Rust contributor familiar with the docs.rs infrastructure. “By defaulting to a single target, we cut build times and server load significantly, which helps the entire ecosystem.”

Docs.rs serves documentation for over 100,000 crates, and the change is expected to reduce its overall compute footprint by up to 40%.

What This Means for Crate Maintainers

Unless a crate explicitly requests additional targets, docs.rs will now build docs for only the default target, typically x86_64-unknown-linux-gnu. Maintainers who need cross‑platform documentation must update their Cargo.toml.

“This is a good default, but it’s a breaking change for any crate that relied on automatic multi‑target builds,” said Mara Bos, a prominent Rust community leader. “The fix is simple—just list your targets explicitly.”

How the Default Target Is Chosen

If you do not set default-target in your [package.metadata.docs.rs] section, docs.rs uses its build server’s target, which is x86_64-unknown-linux-gnu. You can override it like so:

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

How to Build for Additional Targets

To restore the old behavior (or to define your own set), use the targets key in your Cargo.toml:

[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 builds exactly those targets. Any target available in the Rust toolchain is still supported.

Timeline and Urgency

The change takes effect on May 1, 2026. Crate maintainers are urged to review their documentation builds well before that date to avoid surprises.

“We recommend that every crate with a non‑trivial user base explicitly declare its desired targets,” added Alex Crichton. “It’s a one‑time change that gives you full control.”

For more details, consult the official docs.rs documentation.