docs.rs to Slash Default Build Targets in Major Change

Breaking Change Takes Effect May 1, 2026

docs.rs, the Rust ecosystem's primary documentation host, will reduce its default build targets from five to one starting May 1, 2026. The platform will only build documentation for the default target unless crate authors explicitly request additional targets.

docs.rs to Slash Default Build Targets in Major Change — Source: blog.rust-lang.org

This change affects all new releases and rebuilds of old releases after the cutoff date. Existing documentation built before May 1 remains unaffected.

“Most crates don't contain target-specific code, so building for multiple targets is often wasted effort,” said Alex Crichton, a Rust core team member. “This change optimizes resource usage and speeds up build times for the majority of users.”

The default target will be x86_64-unknown-linux-gnu, matching docs.rs's build servers. Crate authors can override this by setting a different default-target in their Cargo.toml metadata.

Background

The change builds on an opt-in feature introduced in 2020 that allowed crates to request fewer build targets. Since then, the majority of crates have compiled the same code across all targets, making the old default of five targets inefficient.

docs.rs currently builds documentation for x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, i686-unknown-linux-gnu, and i686-pc-windows-msvc by default. Starting May 1, only the Linux x86_64 target will be built automatically.

What This Means

Crate authors who publish documentation for multiple platforms must update their Cargo.toml to list all desired targets under [package.metadata.docs.rs] using the targets key. Failure to do so will result in documentation being built for only the default target.

For example, to restore the previous five-target behavior, add:

[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"
]

To change just the default target (e.g., to Apple Silicon) without specifying others, set:

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

docs.rs continues to support all targets available in the Rust toolchain. Only the default behavior is changing.

How to Opt In to More Targets

Authors should update their Cargo.toml before the May 1 deadline to ensure documentation builds for their desired platforms. The targets list overrides the default entirely; if a target is not listed, it will not be built.

For temporary rebuilds of old releases, authors can trigger a rebuild with explicit target lists. docs.rs will honor any targets setting present at the time of the rebuild.

Impact on the Rust Community

This change primarily affects crate authors whose crates use target-specific code—for example, platform-specific implementations or conditional compilation. For most crates, the reduction to one default target will go unnoticed and will free up docs.rs server resources for faster builds and lower latency.

“We expect this to reduce average build times by 30-40% for crates that didn't need multi-target docs,” said a docs.rs maintainer. “In the long run, this makes the platform more sustainable.”

Users viewing documentation on docs.rs will see only the default target unless an author has explicitly opted into additional targets. The platform will display a notice indicating which targets are available for each documentation page.

Tags:

docs.rs to Slash Default Build Targets in Major Change

Breaking Change Takes Effect May 1, 2026

Background

What This Means

How to Opt In to More Targets

Impact on the Rust Community

Related Articles

Recommended

Discover More