docs.rs Shifts to Single Default Target: What You Need to Know

Overview

If you publish Rust crates, you may have noticed that docs.rs currently builds documentation for five different targets by default. That behavior is about to change. Starting May 1, 2026, docs.rs will build documentation for only the default target unless you explicitly request additional ones. This article explains the change, why it’s happening, and how to adjust your crates to ensure your docs are built exactly as you need.

Timeline

The new default will take effect on 2026-05-01. This is a breaking change in the sense that crates that rely on the current five-target default will automatically see fewer targets built after that date—unless they update their metadata. The change applies to:

• New releases published on or after that date
• Rebuilds of old releases triggered by docs.rs

Existing documentation pages remain unaffected; only future builds will follow the new rule.

Why This Change?

Docs.rs first introduced the ability to opt into fewer build targets back in 2020. Since then, the team observed that the vast majority of crates do not compile platform-specific code. Building documentation for five targets each time is often unnecessary and wastes resources. The new default—building for just one target—reduces build times, saves server capacity, and better matches what most crates actually need.

As the Rust ecosystem grows, efficient use of CI and documentation infrastructure becomes crucial. This change aligns docs.rs with the principle of sensible defaults: start minimal, let users opt-in when more is required.

Which Crates Are Affected?

This change only affects crates that:

• Do not define a targets list in their [package.metadata.docs.rs] section of Cargo.toml, and
• Currently rely on the implicit five-target default.

If your crate uses conditional compilation (e.g., #[cfg(target_os = "linux")]) or provides platform-specific APIs, you probably want documentation for multiple targets. Otherwise, the single-target default is likely sufficient—and faster.

How Is the Default Target Chosen?

If you do not set a custom default-target, docs.rs uses the target of its build servers:

x86_64-unknown-linux-gnu

You can override this by setting default-target in your Cargo.toml metadata. For example, to build for macOS by default:

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

This changes only the single target built when targets is not specified. If you need multiple targets, you must list them explicitly (see next section).

How to Build Documentation for Additional Targets

If your crate requires documentation for more than one target, define the full list explicitly in your Cargo.toml under the targets key. For example, to replicate the old default five targets:

[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—no more, no less. You can include any target that the Rust toolchain supports. The default-target setting is ignored when targets is present.

Example: Adding a Custom Target

Suppose you maintain a crate that uses SIMD optimizations for ARM. You could request:

[package.metadata.docs.rs]
targets = ["aarch64-unknown-linux-gnu"]

This is fine—you’re not forced to include the five old targets. The only change is the default behavior; the infrastructure still supports any target.

Summary

Starting May 1, 2026, docs.rs will build documentation for only the default target unless you specify a custom targets list. This is a resource‑saving optimization that better serves most crates. To keep the old five‑target behavior (or any custom set), simply add the [package.metadata.docs.rs] section with targets to your Cargo.toml.

Remember, this change only affects new releases and rebuilds after the deadline. Existing documentation pages remain untouched. For most crates, nothing needs to change—but if your crate relies on multiple platforms, a small metadata update will ensure your docs continue to cover all your users.

For more details, see the official docs.rs documentation.