docs.rs Streamlines Builds: Defaulting to a Single Target in 2026

Introduction

Starting May 1, 2026, docs.rs will change its default build behavior to generate documentation for only one target platform instead of the current five. This update refines a policy first introduced in 2020, when docs.rs gave crate authors the option to request fewer build targets. The change aims to reduce build times, conserve resources, and align with the reality that most crates produce identical code across platforms.

This article explains what’s changing, why it matters, and how you can customize your crate’s documentation builds to include multiple targets if needed.

What Is Changing?

Previously, if a crate did not explicitly define a targets list in its docs.rs metadata, the service would build documentation for a default set of 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, the default will shrink to just one target: the same architecture as docs.rs build servers (x86_64-unknown-linux-gnu). Only new releases and rebuilds of old releases will be affected; existing documentation remains unchanged unless manually rebuilt.

Why the Change?

Most crates do not contain target-specific code, meaning the generated documentation differs only in the platform banner at the top. Building five targets instead of one therefore wastes compute time and storage. This change reduces docs.rs resource usage significantly and speeds up new documentation uploads. It also encourages crate authors to explicitly declare which targets matter for their crate, improving transparency.

How the Default Target Is Chosen

If you do not set a default-target in your docs.rs metadata, the service uses x86_64-unknown-linux-gnu — the platform of the build servers. You can override this by adding the default-target field to your Cargo.toml:

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

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

Requesting Additional Targets

If your crate truly needs documentation for multiple platforms — for example, because it uses conditional compilation (#[cfg(...)]) that produces different APIs — you should explicitly list all required targets in the Cargo.toml metadata:

[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. This list overrides the default entirely — you must include every target you want, including the default one if you still need it.

Supported Targets

docs.rs continues to support any target available in the Rust toolchain. Only the default behavior is changing. You can still request exotic targets like aarch64-linux-android or wasm32-unknown-unknown by adding them to your targets array.

Impact on Existing Crates

This change affects:

• New crate releases published after May 1, 2026
• Rebuilds of older releases triggered manually or by a new version of the release process

Crates that already have a targets list defined will see no change in behavior. Crates that relied on the old default list will now only generate documentation for the build server’s target (x86_64-unknown-linux-gnu) unless they update their metadata.

What Should You Do?

1. Check if your crate uses #[cfg(target_os = ...)] or similar. If not, you likely need only the default target.
2. If you need multiple targets, add a targets list to your [package.metadata.docs.rs] before May 1, 2026, to avoid a single-target build after that date.
3. Consider setting a default-target if the default Linux target is not appropriate.

Conclusion

The upcoming change to docs.rs default build behavior is a sensible optimisation that reduces waste and encourages explicit configuration. By moving from five targets to one, the service saves resources while still allowing crate authors to easily request as many targets as they need. If your crate requires cross-platform documentation, update your Cargo.toml today to ensure a smooth transition after the May 1, 2026 deadline.