Breaking Change Effective May 1, 2026
Starting on May 1, 2026, docs.rs will implement a significant change to its default build behavior. Previously, when a crate did not specify a targets list in its docs.rs metadata, the platform would build documentation for a default set of five targets. After the change, documentation will be built for only the default target unless additional targets are explicitly requested. This update represents the next phase of a modification first introduced in 2020, when docs.rs added support for opting into fewer build targets.
This change applies exclusively to:
- New releases of crates
- Rebuilds of existing releases
Existing documentation built before May 1, 2026 remains unaffected.
Why This Change?
The majority of crates do not compile different code for different targets. Building documentation for multiple targets when not needed wastes computational resources and increases build times. By defaulting to a single target, docs.rs reduces server load, speeds up documentation generation, and conserves energy—benefiting both the platform and its users. This optimization aligns with the common practice of targeting a single platform (e.g., x86_64-unknown-linux-gnu) and only expanding when a crate truly requires platform-specific content.
How Is the Default Target Chosen?
If you do not set default-target in your crate's metadata, docs.rs will use the target of its build servers, which is x86_64-unknown-linux-gnu. You can override this by adding the default-target key to your docs.rs metadata in Cargo.toml:
[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"
This option is ideal for crates that need documentation tailored to a specific platform, such as macOS or Windows, but do not require multiple targets.
How to Build Documentation for Additional Targets
If your crate requires documentation to be built for more than the default target, define the full list explicitly in your Cargo.toml. 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 targets is set, docs.rs will build documentation for exactly those targets. This method gives you full control: you can include any target available in the Rust toolchain. Only the default behavior is changing—the ability to build for every supported target remains intact.
For most crates, sticking with the default single target is sufficient. If you maintain a library with platform-specific code (e.g., using cfg attributes or conditional compilation), consider specifying a targets list to ensure your documentation covers all relevant platforms.
Action required: Review your crate's docs.rs metadata before May 1, 2026. If your crate currently relies on the default five-target behavior, update your Cargo.toml to include the desired targets. Visit the docs.rs build configuration documentation for more details.