Docs.rs to Default to Single Build Target Starting May 2026

Docs.rs Makes a Breaking Change: Fewer Targets by Default

Starting May 1, 2026, docs.rs will build documentation for only the default target unless crate authors explicitly request more. This marks a significant shift from the current default of five targets.

“Most crates don’t compile different code for different targets, so building fewer targets by default is a better fit for most releases,” said the docs.rs team in their announcement. “It also reduces build times and saves resources on docs.rs.”

What’s Changing?

Today, if a crate does not define a targets list in its docs.rs metadata, docs.rs builds documentation for five default targets. After May 1, 2026, only one target – the system’s default – will be built unless the author specifies otherwise.

This change applies only to new releases and rebuilds of old releases. Existing documentation pages are not affected.

Background

This is the next step in a change first introduced in 2020, when docs.rs added support for opting into fewer build targets. The original five-target default was chosen when Rust’s cross-compilation support was less mature.

The team found that the vast majority of crates produce identical documentation across targets. Reducing the default to one target cuts build time and server load, making the service more sustainable.

How Is the Default Target Chosen?

If you do not set a default-target in your docs.rs metadata, docs.rs uses the target of its build servers: x86_64-unknown-linux-gnu. You can override that by adding a default-target key in your Cargo.toml:

[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"

How to Build for Additional Targets

If your crate requires documentation for more than one target, define the full list explicitly in your Cargo.toml:

[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. The service still supports any target available in the Rust toolchain – only the default behavior is changing.

What This Means

For crate authors who rely on multiple targets (e.g., cross-platform libraries), this change requires a one-time metadata update. Failure to specify targets will result in documentation being generated only for the default target.

The docs.rs team emphasizes that this saves server resources and speeds up builds: “Most releases don’t need five targets. This change aligns docs.rs with the real needs of the ecosystem.”

To avoid surprises, examine your Cargo.toml now. If you need cross-platform docs, add a targets list before May 1, 2026.

Timeline and Migration

The change takes effect on May 1, 2026. Until then, the old default (five targets) remains active. After that date, any new release or rebuild will use the new single-target default unless targets is specified.

No action is needed for crates that already set a targets list. If you rely on the default five targets, update your metadata before the deadline.