Starting May 1, 2026, docs.rs will implement a significant change to how it builds documentation for Rust crates. Instead of building for five default targets, it will now build for only the default target unless crate authors explicitly specify additional targets. This move refines a feature introduced in 2020 that allowed opting out of multi-target builds. Since most crates have platform-independent code, this change reduces build times and saves server resources. It applies only to new releases and rebuilds of old releases. Below, we break down the details and how to adjust your configuration.
What is changing about documentation builds on docs.rs?
Currently, if a crate does not set a targets list in its [package.metadata.docs.rs] section, docs.rs automatically builds documentation for five predefined targets: x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, i686-unknown-linux-gnu, and i686-pc-windows-msvc. Starting May 1, 2026, the default behavior will switch to building for only one target: the build server’s own target (x86_64-unknown-linux-gnu) or any target you specify as default-target. This is a breaking change that affects all crates that rely on the old default.
When does this new default take effect?
The new behavior becomes effective on May 1, 2026. All crate releases published on or after that date will be subject to the single-target default. Also, any manual rebuild requests for older releases initiated after the cutoff will use the new default. Releases built before that date and not rebuilt will retain their originally generated documentation. This phased transition gives crate authors time to update their configuration if needed.
Why is docs.rs making this change?
Building documentation for multiple targets is resource-intensive. The vast majority of Rust crates do not have platform-specific code—they compile identically across all targets. For those crates, generating docs for five targets is unnecessary and wasteful. By defaulting to a single target, docs.rs can reduce build times for most releases, save server resources, and deliver documentation faster. This change aligns with the principle that optional customizations should be explicit: if a crate has target‑dependent code, the author should opt‑in to multi‑target builds. It also simplifies the configuration for most users.
How is the default target chosen?
If you do not set a default-target in your [package.metadata.docs.rs] section, docs.rs will use its own build server’s target, which is x86_64-unknown-linux-gnu. To override this, add a default-target key to your metadata. For example:
[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"This setting determines the single target used when you do not provide an explicit targets list. It is recommended for crates that primarily target a different platform (e.g., macOS) but still have no need for multiple platform docs.
How do I request documentation for additional targets?
If your crate genuinely requires documentation for multiple targets—for example, because it uses conditional compilation or exposes platform‑specific APIs—you must define the full list explicitly in your Cargo.toml. Use the targets key under [package.metadata.docs.rs]. 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 builds documentation for exactly those targets, ignoring the default-target and the single‑target default. Any target available in the Rust toolchain can be listed. Only the default behavior is changing—custom configurations remain fully supported.
Will existing releases be affected?
No. The change only applies to new releases published after May 1, 2026, and to rebuilds of old releases initiated on or after that date. Already‑built documentation for older releases will remain untouched. If you do nothing, your existing documentation stays as it is. However, if you later trigger a rebuild (e.g., via the “Rebuild” button on docs.rs), the new default behavior will apply to that rebuild unless you have updated your metadata first.