Starting May 1, 2026, docs.rs will change its default build behavior, building documentation for only one target instead of five. This move aims to reduce resource usage and streamline documentation generation. Here are the key questions and answers to help you understand the update and adjust your crate configuration.
What change is docs.rs making on May 1, 2026?
On 2026-05-01, docs.rs will break its current build behavior. Today, if a crate does not specify a targets list in its docs.rs metadata, the platform builds documentation for a default set of five targets. After the change, it will build only for a single default target unless additional targets are explicitly requested. This is a significant shift that aligns docs.rs with the fact that most crates don't compile platform-specific code, making a single-target default more efficient for the majority of releases.
Why is docs.rs reducing the number of default build targets?
The primary motivation is efficiency. Building documentation for five targets by default consumes more resources and takes longer than necessary, especially since most crates compile the same code across all platforms. By switching to one default target, docs.rs reduces build times and saves computational resources on its servers. This change is the next step in a plan that began in 2020, when docs.rs first allowed crate authors to opt into fewer build targets. The new default simply applies that optimization to all crates that haven't explicitly chosen a custom target list.
Who is affected by this change?
The change affects only new releases and rebuilds of old releases after May 1, 2026. Existing documentation remains untouched. If your crate already defines a custom targets list in its [package.metadata.docs.rs] section, nothing changes. Crate authors who rely on the default five-target behavior without setting their own list will see documentation generated for a single target unless they update their Cargo.toml. Users of those crates may notice that platform-specific documentation (e.g., Windows vs. Linux) is no longer available by default, but authors can easily add back additional targets.
How is the default target chosen, and can I override it?
If you do not set a default-target in your docs.rs metadata, docs.rs uses its build server's target, which is x86_64-unknown-linux-gnu. You can override this by adding a default-target field in your Cargo.toml under [package.metadata.docs.rs]. For example, to target macOS, you can set: default-target = "x86_64-apple-darwin". This override determines the single target that will be built by default if you don't specify a full targets list. It's a straightforward way to align the default documentation with your primary development platform or the most common user environment.
How can I request documentation for additional targets?
To build documentation for more than the default target, you must explicitly list all desired targets in your Cargo.toml. Add a targets array under [package.metadata.docs.rs]. For instance:
[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 documentation for exactly those targets—not more, not less. This gives you full control. Remember that the default-target field is ignored when targets is present. The list can include any target available in the Rust toolchain; only the default behavior has changed.
Does docs.rs still support building for any Rust target?
Absolutely. The change only affects the default build behavior. docs.rs continues to support every target available in the Rust toolchain. Whether you need documentation for ARM, RISC-V, or esoteric embedded platforms, you can still specify them in the targets array. The platform's infrastructure remains capable of building for any target; it's just that crate authors must now explicitly opt into multi-target builds. This flexibility ensures that crates with platform-specific APIs (like those using #[cfg(target_os = "windows")] can still provide complete documentation across all relevant targets, as long as the author configures the list.
What led to this change? Was there a previous opt-in?
This update builds on a feature introduced in 2020, when docs.rs first allowed crate authors to choose to build for fewer targets. At that time, the default remained five targets, and the opt-in was for reducing the count. Since then, the team observed that most crates don't actually need multi-target documentation—they compile the same code everywhere. Therefore, making the resource-friendly option the new default is a natural progression. It simplifies the experience for the majority of crate authors while still giving full control to anyone who needs platform-specific documentation. The gradual rollout ensured that the community had time to adapt, and now the final step is to switch the default.