docs.rs to Slash Default Build Targets to One Starting May 2026

By ● min read

Breaking News — docs.rs will build documentation for only one target by default from May 1, 2026, a fundamental shift from the current five-target default that has been in place for years.

The change is designed to reduce build times and conserve server resources, aligning docs.rs with the reality that most crates compile identically across targets.

“This is the next step in our effort to streamline documentation builds,” said a docs.rs team member. “Most crates don't vary by target, so building fewer by default makes sense.”

What’s Changing

Today, if a crate’s documentation metadata does not specify a targets list, docs.rs builds documentation for a default list of five targets. Starting May 1, 2026, that default will shrink to just one target.

docs.rs to Slash Default Build Targets to One Starting May 2026 — Source: blog.rust-lang.org

The change applies only to new releases and rebuilds of old releases. Crate authors who have already explicitly set a targets list will see no difference.

Choosing the Default Target

If a crate does not set a default-target in its [package.metadata.docs.rs] section, docs.rs will use x86_64-unknown-linux-gnu — the platform of its build servers.

Authors can override this default by specifying their preferred target:

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

Requesting Additional Targets

If your crate requires documentation for more than one target, you must define the full list explicitly in 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 builds documentation for exactly those targets. The service still supports any target available in the Rust toolchain; only the default behavior is changing.

Background

The move is the next phase of a change first introduced in 2020, when docs.rs added the ability for crate authors to opt into building fewer targets. At that time, the default remained at five targets to avoid breaking existing builds.

Since then, the docs.rs team has monitored usage data and found that the vast majority of crates compile the same code regardless of target. Reducing the default further was a logical progression.

What This Means

For most crate authors, this change will go unnoticed — their documentation will continue to build for the single default target, and users will still see correct docs for that platform.

However, authors of crates that use platform-specific code (e.g., FFI, OS-specific APIs) must update their metadata before May 1 to ensure documentation is generated for all relevant targets. Failure to do so will result in docs only being available for the default target.

The docs.rs team recommends that all crate authors review their Cargo.toml and, if unsure, explicitly set a targets list to avoid surprises after the deadline.

Tags: