Breaking Change: docs.rs Default Targets Reduced to One
Beginning May 1, 2026, the Rust documentation hosting service docs.rs will change its default build behavior. Instead of building documentation for five targets by default, it will only build for the default target unless additional targets are explicitly requested.
This update affects new releases and rebuilds of old releases. Existing documentation remains unchanged.
“This change is the next step in a process we started in 2020,” said a docs.rs spokesperson. “Most crates don’t compile different code per target, so building fewer targets by default better fits the needs of the majority of releases.”
How the Default Target Is Chosen
If a crate does not specify a default-target in its Cargo.toml metadata, docs.rs uses its own build server target: x86_64-unknown-linux-gnu. Developers can override this by setting the default-target field under [package.metadata.docs.rs].
For example:
[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"Building for Additional Targets
Crates that require documentation for multiple targets must now define the full targets list explicitly. “If you need builds for more than one platform, specify them in the targets array,” explained the spokesperson. “docs.rs will then build documentation for exactly those targets.”
An example configuration:
[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"
]docs.rs still supports any target available in the Rust toolchain. Only the default behavior is changing. The service plans to continue optimizing resource usage.
Background
The change builds on a 2020 initiative that allowed crate authors to opt into fewer build targets. Since then, most crates have not required multi-target builds because they contain no platform-specific code. Building for only one target by default reduces build times and conserves server resources.
“This is a logical progression,” a Rust documentation team member noted. “We’ve seen that the vast majority of crates benefit from a single-target default. It’s both efficient and simpler for crate authors.”
What This Means for Crate Authors
For the majority of crates with no conditional compilation, no action is needed. Their documentation will continue to build, just for a single target. However, crates that rely on platform-specific features—such as operating system APIs or hardware intrinsics—must now explicitly declare their needed targets.
Crate authors should review their Cargo.toml documentation metadata before May 1, 2026. If your crate uses #[cfg] attributes for different platforms, you should update the targets list to ensure the documentation covers all intended platforms.
The change will also reduce the load on docs.rs, potentially speeding up builds for all users. “By defaulting to one target, we free up capacity for quicker builds across the ecosystem,” added the spokesperson.