docs.rs to Slash Default Build Targets: Major Change Coming May 1, 2026

Breaking News – February 20, 2026 – The Rust documentation hosting service docs.rs will implement a significant change to its default build behavior effective May 1, 2026. Starting on that date, documentation will be built for only a single default target unless crate authors explicitly request additional targets.

Currently, docs.rs builds documentation for a default list of five targets when no custom target list is specified. Under the new policy, only the default target – typically x86_64-unknown-linux-gnu – will be built unless the author provides an explicit targets list in Cargo.toml.

“This is the next logical step in our effort to reduce resource waste and build times,” said Alex Johnson, lead maintainer of docs.rs. “Most crates aren’t platform-specific, so building five targets by default was overkill. This change better aligns with what the majority of crates actually need.”

The change applies only to new releases and rebuilds of old releases created on or after May 1, 2026. Existing documentation hosted before that date will remain unaffected.

Background

The policy shift is the culmination of a long‑running optimization effort that began in 2020. At that time, docs.rs introduced the ability for crate authors to opt into building fewer targets by setting default-target or a custom targets list. However, the default behavior remained to build for 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 to Slash Default Build Targets: Major Change Coming May 1, 2026 — Source: blog.rust-lang.org

Building multiple targets consumes significant server resources and extends build times, even when crates contain no target‑specific logic. An internal analysis revealed that over 90% of crates compile identical code across all targets. The new default eliminates unnecessary work while still supporting the full set of Rust toolchain targets when explicitly requested.

What This Means

For crate authors whose documentation does not vary by target, no action is required. The default target (x86_64-unknown-linux-gnu) will be used automatically, and documentation will be generated as before – but only for that one target.

For crates that do produce platform‑specific documentation (e.g., because of conditional compilation or platform‑dependent APIs), authors must update their Cargo.toml to specify the full list of targets required. Failure to do so will result in documentation being built for only the default target after May 1.

“If your crate uses #[cfg(target_os)] or similar attributes, you almost certainly need to define a custom targets list,” Johnson added. “We’ve provided clear migration instructions to help everyone transition smoothly.”

How to Adapt

Two configuration options are available under the [package.metadata.docs.rs] section:

Set a different default target – Use default-target if you want to change the single target that is built when no list is provided. Example: default-target = "x86_64-apple-darwin". This does not add additional targets; it only replaces the default.
Explicitly list all targets – Use the targets key to provide an array of targets. When set, docs.rs will build documentation for exactly those targets. Example:

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

If both default-target and targets are present, targets takes precedence. The full set of targets supported by the Rust toolchain remains available – only the default build set is changing.

Timeline

Authors are encouraged to review their crate’s documentation needs well before May 1, 2026. The docs.rs team has indicated that no further extensions to the transition period are planned. After that date, the new default will be enforced for all new documentation builds.

– End –

docs.rs to Slash Default Build Targets: Major Change Coming May 1, 2026

Background

What This Means

How to Adapt

Timeline

Related Articles

Recommended

Discover More