docs.rs Overhauls Default Build Configuration: Only Single Target by Default Starting May 2026

Breaking Change Announced

On May 1, 2026, docs.rs will implement a major change to its default build behavior. Currently, when a crate does not specify a targets list in its docs.rs metadata, the platform builds documentation for five default targets. Starting that date, only the default target will be built unless additional targets are explicitly requested.

docs.rs Overhauls Default Build Configuration: Only Single Target by Default Starting May 2026 — Source: blog.rust-lang.org

This decision marks the culmination of a shift first introduced in 2020, when docs.rs added the ability for crate authors to opt into fewer build targets. “Most crates do not compile different code for different targets, so building fewer targets by default is a better fit for most releases,” explained a docs.rs maintainer. The change also reduces build times and conserves server resources.

Background

The transition has been gradual. In 2020, docs.rs gave crate authors the option to reduce the number of targets built. Now, that option becomes the default. The platform has observed that the vast majority of crates produce identical documentation across all targets, making multi‑target builds wasteful for most projects.

“This change only affects new releases and rebuilds of old releases,” the maintainer clarified. Existing documentation for previously published crates will remain unchanged unless a rebuild is triggered.

What This Means

Crate authors who rely on documentation for multiple targets—such as Windows, macOS, and Linux—must now explicitly list those targets in their Cargo.toml. Without an explicit targets list, docs.rs will only build for the default target, which is x86_64-unknown-linux-gnu (the platform of the build servers).

This could break existing documentation workflows for crates that conditionally compile platform‑specific code or that have users on multiple platforms expecting per‑target docs. Authors should review their documentation needs before the deadline.

How to Adapt

Setting the Default Target

If you want a different default target than x86_64-unknown-linux-gnu, use the default-target key in your docs.rs metadata:

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

This instructs docs.rs to use that target as the single default when no targets list is provided.

Building for Multiple Targets

To restore documentation for multiple targets, define the full list explicitly:

[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 the targets key is set, docs.rs will build documentation for exactly those targets, ignoring the default. The platform continues to support any target available in the Rust toolchain—only the default behavior is changing.

Important Dates

The new behavior takes effect on May 1, 2026. Crate authors should update their metadata before that date to avoid unintended reductions in documentation coverage. For more details, consult the docs.rs about page.

Looking Ahead

This adjustment aligns docs.rs with the reality that most Rust crates are platform‑agnostic. By reducing the default build load, the service can allocate resources more efficiently and potentially speed up builds for all users. However, for the minority of crates that need cross‑target documentation, the explicit‑list approach adds a small maintenance burden.

“We believe this change is a net positive for the ecosystem,” the maintainer stated. “It encourages crate authors to think about their actual target requirements and helps us keep docs.rs fast and reliable.”

Tags: