Understanding docs.rs's Upcoming Default Build Target Change
Starting May 1, 2026, docs.rs will adjust how it builds documentation for Rust crates. Instead of building for five targets by default, it will only build for the platform target unless you explicitly request more. This guide explains the change, why it's happening, and how to configure your Cargo.toml to get the results you need.
What exactly is changing on May 1, 2026?
Currently, if a crate doesn't specify a list of targets in its docs.rs metadata, docs.rs builds documentation for a default set of five targets. After May 1, 2026, docs.rs will instead build for only a single default target unless you explicitly declare additional targets. This move refines a feature introduced in 2020 that let crates opt into building fewer targets. Since most crates have platform-independent code, the new default saves compute resources and reduces build times.
Why is docs.rs making this change?
The primary motivation is efficiency. Building documentation for every available target for every crate is wasteful – most crates compile identical code regardless of the target platform. By switching to a single default target, docs.rs cuts down on unnecessary builds, speeds up documentation generation, and reduces server load. The change also aligns with community feedback: a 2020 opt-in experiment showed that very few crates actually needed multiple targets, so making it opt-out was the logical next step.
How is the default target chosen?
If you don't set the default-target in your Cargo.toml metadata, docs.rs will use the build server's own target: x86_64-unknown-linux-gnu. You can override this default by adding a default-target field under [package.metadata.docs.rs]. For example, to target a macOS system, use:
[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"This tells docs.rs which single target to build for when no explicit target list is provided.
How do I request additional build targets?
If your crate's documentation must be built for more than the default target, define the complete list explicitly in your Cargo.toml under the targets key. For instance:
[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 you set targets, docs.rs will build documentation for exactly those targets and ignore the default-target setting. You can include any target that is available in the Rust toolchain.
Does this change affect existing crate releases?
Only new releases and rebuilds of old releases are affected. Previously published versions that were already built will remain unchanged. However, if you trigger a rebuild for an old release, it will use the new default behavior (single target) unless you update the metadata. To preserve multiple targets for an older release, you'll need to edit the Cargo.toml and trigger a new rebuild.
What if my crate needs the old default (5 targets)?
To keep the same behavior as before, simply set the targets list to the original 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. This will ensure docs.rs builds documentation for all five platforms as it did before the change. If you only need one specific target, you can omit the list and only set default-target.
Where can I learn more about docs.rs configuration?
For complete details on available metadata options, see the official Cargo documentation on docs.rs metadata. The docs.rs API documentation also explains how rebuilds work and how to trigger them.