Breaking: docs.rs to Reduce Default Build Targets to One
Starting May 1, 2026, docs.rs will implement a dramatic shift in its build behavior: instead of automatically generating documentation for five default targets, the service will produce docs for only the default target unless additional platforms are explicitly requested. This change, announced by the Rust documentation team, aims to streamline builds and conserve resources.
"Most crates don't require multiple targets because they compile the same code across architectures," said a spokesperson for the docs.rs team. "This change better serves the majority of releases while improving overall efficiency."
What's Changing?
Currently, if a crate does not specify a target list in its [package.metadata.docs.rs], docs.rs builds documentation for five targets: x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, i686-unknown-linux-gnu, and i686-pc-windows-msvc. After the cutover, only the default target (usually x86_64-unknown-linux-gnu) will be built automatically.
The change affects only new releases and rebuilds of old releases. Existing documentation remains untouched.
Background
This update is the next step in a process that began in 2020, when docs.rs first introduced opt-in support for fewer build targets. The move toward reduced defaults reflects a broader understanding that unnecessary multi-target builds waste computation time and cache space.
"We've seen that the vast majority of crates don't leverage conditional compilation per target," explained a Rust infrastructure engineer. "Reducing the default from five to one aligns with real-world usage and cuts build times significantly."
The change is expected to reduce the load on docs.rs servers and speed up documentation delivery for users.
How Is the Default Target Chosen?
If no default-target is specified, docs.rs uses its build server's native target: x86_64-unknown-linux-gnu. However, crate authors can override this by setting the default-target key in their Cargo.toml metadata:
[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"For more details on configuration, see how to add additional targets.
How to Build Documentation for Additional Targets
If your crate requires documentation for multiple platforms, you must explicitly list them using the targets array in [package.metadata.docs.rs]:
[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, no more, no less. All targets available in the Rust toolchain are still supported—only the default behavior is changing.
What This Means
For the majority of crate maintainers, this change will be invisible—their docs will build faster and resources will be saved. But for crates that genuinely need multiple targets (e.g., those using conditional compilation for operating system–specific code), action is required before May 1, 2026.
"We encourage all crate authors to review their documentation needs," the docs.rs team advised. "If you're relying on the old default five targets, update your Cargo.toml now to avoid missing target coverage."
The shift underscores a broader trend in Rust ecosystem infrastructure: prioritize efficiency over blanket defaults, and give users fine-grained control when they need it.