Key Change: Fewer Build Targets by Default
As of May 1, 2026, docs.rs will implement a significant shift in its build behavior. Instead of automatically building documentation for five default targets, it will now build only for the single default target unless crate authors explicitly request additional ones. This adjustment represents the next milestone in a gradual optimization that began back in 2020, when docs.rs first allowed users to opt into a reduced set of build targets.
The motivation is straightforward: most crates contain platform-independent code that compiles identically across different targets. For these crates, building documentation for multiple targets is unnecessary, consumes extra build time, and wastes valuable server resources. By reducing the default number of targets, docs.rs becomes more efficient for the majority of crate releases while still offering flexibility for those that genuinely need multi-target documentation.
Which Crate Releases Are Affected?
This change applies exclusively to:
- New releases of crates uploaded after May 1, 2026
- Rebuilds of existing releases (e.g., triggered by documentation rebuild requests)
Existing documentation pages remain unchanged unless explicitly rebuilt. Crates that already define a targets list in their docs.rs metadata are unaffected, as their explicit configuration takes precedence.
How Is the Default Target Selected?
If your Cargo.toml does not specify a default-target under [package.metadata.docs.rs], docs.rs will use x86_64-unknown-linux-gnu — the architecture of its build servers. To override this, set your preferred default target explicitly:
[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"
This single target will be the one built by default for your crate. If you need documentation for multiple platforms, you must list them manually using the targets array (see below).
How to Request Additional Build Targets
When your crate requires documentation for more than one target — say, because it uses conditional compilation with #[cfg] attributes — you must define the complete list explicitly. Add the following to your Cargo.toml under [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 present, docs.rs ignores the default target and builds documentation for exactly those listed targets — no more, no less. This explicit approach gives you full control over which platforms are documented.
Importantly, docs.rs still supports any target available in the Rust toolchain. The change only affects the default behavior; you can request niche or custom targets by listing them in the targets array as long as they are recognized by the Rust compiler.
Background and Rationale
The decision to cut down the default number of build targets did not happen overnight. In 2020, docs.rs introduced the ability to opt into fewer targets as an experimental feature. Since then, community feedback and usage patterns have confirmed that the vast majority of crates compile identically across platforms. Building documentation for five targets by default (x86_64 and i686 variants for Linux, macOS, and Windows) often resulted in redundant output pages that displayed identical content, wasting both build time and storage.
By reversing the default — building only one target unless more are explicitly requested — docs.rs aligns with the principle of least surprise. Crate authors who want multi-target documentation are typically aware of their platform-specific code and can easily add the targets list. Those who don't need it benefit from faster builds and reduced load on the infrastructure.
This change also sets a precedent for further resource optimizations in the future. As the Rust ecosystem grows, efficiency improvements like this one help keep docs.rs sustainable and responsive.
For a step-by-step guide on updating your configuration, see the “How to Request Additional Build Targets” section above. Crate maintainers are encouraged to review their Cargo.toml before the May 1 deadline to ensure their documentation builds as intended.