Breaking: docs.rs Cuts Default Build Targets from Five to One
Starting May 1, 2026, docs.rs will change its build behavior to compile documentation for only the default target unless explicitly requested otherwise. This shift from the current five-target default aims to reduce build times and conserve server resources.
“Most crates do not contain target-specific code, so building for multiple targets is often unnecessary,” explained a docs.rs maintainer. “This change streamlines operations while giving developers full control when they need multi-target docs.”
Background
This decision is the next step in a process that began in 2020, when docs.rs first allowed crate authors to opt into fewer build targets. Despite that option, the default remained five targets—a choice that now aligns poorly with the needs of most Rust projects.
The change applies only to new releases and rebuilds of old releases; previously built documentation will remain unaffected. Developers who require documentation for additional targets can still request them explicitly.
How the Default Target Is Chosen
If no default-target is set in Cargo.toml metadata, docs.rs automatically uses the build server’s architecture: x86_64-unknown-linux-gnu. However, users can override this by adding a custom default target:
[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"This flexibility ensures that the default reflects the developer’s primary platform without requiring a full list of targets.
How to Build Documentation for Extra Targets
To generate docs for multiple targets, crate authors must define the complete list inside [package.metadata.docs.rs]. For 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"
]When the targets field is set, docs.rs builds documentation only for those entries. The platform still supports any target available in the Rust toolchain—only the default behavior is changing.
What This Means
For the majority of crates that compile identical code across targets, this update means faster builds and reduced resource usage on docs.rs. Developers no longer wait for unnecessary documentation generation, and the service can allocate capacity more efficiently.
However, crate authors with platform-specific code (e.g., conditional compilation via cfg) must now explicitly list all required targets. Failure to do so could result in missing documentation for certain platforms after the change takes effect.
“We recommend that all maintainers review their Cargo.toml metadata before May 1, 2026,” the maintainer added. “If your crate has target-specific features, set the targets list now to avoid surprises.” The community is encouraged to test the new behavior by setting default-target or targets in their configuration ahead of the deadline.
For more details, refer to the docs.rs metadata documentation.