Breaking Change Coming May 1, 2026: docs.rs Reduces Default Build Targets
Starting May 1, 2026, docs.rs will build documentation for only the default target by default, a dramatic reduction from the current five-target default. The change aims to cut build times and reduce server load, but requires crate maintainers to explicitly list any additional targets they need.
"This is about matching the behavior to what most crates actually need," said a docs.rs team spokesperson. "The vast majority of Rust crates do not compile different code for different platforms, so building for five targets is wasteful."
Background
The shift builds on a 2020 change that first allowed crates to opt into fewer targets. At that time, docs.rs added support for crate-level target configuration through metadata fields. The current default of five targets was set when the service launched, but usage data now shows that less than 5% of crates customize their target list.
"We've been monitoring build volumes for years," the spokesperson added. "Most users never touch the default, and those who do often only need one or two specific platforms. This change aligns the default with reality."
What Is Changing?
When a crate does not define a targets list in its [package.metadata.docs.rs] section, docs.rs currently builds documentation 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.
After May 1, 2026, if no targets list is provided, only the default target will be built. The default target defaults to x86_64-unknown-linux-gnu (the build server's own architecture), but crate authors can override it using the default-target metadata field.
The change affects only:
• New crate releases
• Rebuilds of existing releases
How to Override the Default Target
Crate maintainers can set a different default target by adding default-target to their Cargo.toml:
[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"How to Build Documentation for Multiple Targets
If your crate requires documentation for more than one target (e.g., because of conditional compilation or platform-specific APIs), define the full target 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 the targets list is set, docs.rs builds documentation for exactly those targets. The service still supports all Rust toolchain targets; only the default behavior is changing.
What This Means for Developers
For maintainers of crates that use conditional compilation per target (e.g., #[cfg(target_os = "windows")]), this change requires explicit action. Without adding a targets list, users visiting docs.rs will only see documentation for a single platform.
"Most crate authors won't notice any difference," said the docs.rs team. "But if you rely on platform-specific docs, you must update your Cargo.toml before May 1 to avoid broken or incomplete documentation pages."
The move also reduces overall build load on docs.rs servers, potentially speeding up the documentation pipeline for all crates. Smaller crates with no target-specific code will see faster rebuilds.
To verify your crate is ready, use cargo doc locally with the appropriate --target flags. Alternatively, check your [package.metadata.docs.rs] configuration now and ensure any needed targets are listed.