Docs.rs Slashes Default Build Targets to One in May 2026 Breaking Change

Breaking Change: Single Target Becomes New Default

Starting May 1, 2026, docs.rs will reduce its default documentation builds from five targets to just one, marking a significant shift in how Rust crate documentation is generated. The change, announced today, means that crates without explicit target configuration will only receive builds for the platform of docs.rs’s build servers—x86_64-unknown-linux-gnu—unless maintainers opt into additional targets.

Docs.rs Slashes Default Build Targets to One in May 2026 Breaking Change — Source: blog.rust-lang.org

“This is the next logical step in a journey we began in 2020, when we introduced the ability to request fewer builds,” said a docs.rs team spokesperson. “Most crates don’t compile platform-specific code, so building for five targets by default wastes resources and prolongs build times.” The move is expected to cut overall build workload on docs.rs by up to 80% for affected crates.

What’s Changing

Currently, when a crate’s Cargo.toml lacks a targets list in its [package.metadata.docs.rs] section, docs.rs builds documentation for the following five targets:

x86_64-unknown-linux-gnu
x86_64-apple-darwin
x86_64-pc-windows-msvc
i686-unknown-linux-gnu
i686-pc-windows-msvc

After May 1, 2026, only the default target will be built unless a crate explicitly lists the desired platforms. The change applies exclusively to new releases and rebuilds of old releases; existing documentation remains unaffected.

How the Default Target is Chosen

If a crate does not set default-target in its metadata, docs.rs uses x86_64-unknown-linux-gnu—the architecture of its own build servers. Maintainers can override this behavior by adding:

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

Requesting Additional Targets

To build documentation for multiple platforms, crates must now define the full list explicitly. For 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 only for the listed platforms. The service continues to support every target available in the Rust toolchain—only the default behavior is changing.

Background

This update is part of a long-running initiative to make docs.rs more efficient. In 2020, the platform first allowed crate authors to opt into fewer build targets, giving them control over which platforms received documentation. Over the subsequent years, the docs.rs team observed that the vast majority of crates are platform-agnostic—they compile identical code across all targets. Building unused documentation not only consumed server resources but also delayed publication of new crate releases.

“The opt-in system worked well, but adoption was limited,” explained the spokesperson. “By flipping the default, we align the service with how crates actually behave, and we free up capacity for other improvements.” The change is expected to be seamless for most maintainers; those who need multi-target documentation need only add a few lines to Cargo.toml.

What This Means

For most crate maintainers: No action is required. If your crate does not use conditional compilation per platform, you will continue to receive documentation for the default target. The reduced build load may even speed up documentation generation for new releases.

For maintainers of cross-platform crates: You must update your Cargo.toml before May 1, 2026, to ensure documentation is built for all target platforms your crate supports. Failing to do so will result in documentation only for the default target (or your custom default).

For the Rust ecosystem: This change promises to reduce docs.rs’s total build time and infrastructure costs, allowing the service to scale more gracefully as the crate registry grows. It also underscores the project’s commitment to resource efficiency and user choice.

The docs.rs team advises all crate authors to review their metadata settings ahead of the deadline. Updated documentation and migration guides are available on the official docs.rs website.