docs.rs to Reduce Default Build Targets Starting May 2026

On May 1, 2026, docs.rs will roll out a breaking change that alters how many targets it builds documentation for by default. This update finalizes a process that began in 2020, when docs.rs first allowed crate authors to opt into building fewer targets. The goal is to better match the needs of most crates while saving time and server resources.

Understanding the Change

Currently, if a crate does not specify a targets list in its docs.rs metadata, the system builds documentation for a default set of five targets. After the change, unless you explicitly request additional targets, only the default target will be built.

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

This adjustment only applies to new releases and rebuilds of existing releases. Already published documentation remains unaffected.

Why this shift? Most crates do not contain target-specific code—they compile identically across platforms. Building documentation for five targets when only one is needed uses unnecessary build time and server capacity. By reducing the default to one target, docs.rs becomes more efficient for the majority of packages, while still allowing those that need multiple targets to opt in easily.

How the Default Target Is Chosen

If you do not set a default-target in your docs.rs metadata, the default target will be x86_64-unknown-linux-gnu—the architecture of the build servers.

You can override this by specifying a different default target in your Cargo.toml:

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

This setting tells docs.rs which single target to use when no explicit targets list is provided.

Building for Additional Targets

If your crate requires documentation for multiple targets (for example, if it uses conditional compilation with cfg for different platforms), you can define the full list explicitly. Use the targets key in [package.metadata.docs.rs]:

[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 will build documentation for exactly those targets. The system still supports any target available in the Rust toolchain—only the default behavior is changing.

What This Means for Your Crates

If your crate is target-agnostic (the vast majority), the change will likely have no negative impact. You'll simply see faster builds and fewer unnecessary documentation pages. However, if your crate does rely on target-specific features—such as operating system or architecture differences—you should update your metadata before May 2026 to ensure documentation covers all relevant targets.

Crates that explicitly list a targets array will continue to work exactly as before. The only change is for crates that rely on the implicit five-target default. Moving forward, if you need more than one target, you must specify them.

To check if your crate is affected, consider whether you use #[cfg(target_os = "...")] or similar conditional compilation directives. If not, the default single-target build is likely sufficient. If yes, review your docs.rs metadata and add the appropriate targets list.

This change is part of an ongoing effort to make docs.rs more responsive and resource-conscious. By reducing unnecessary builds, the service can serve documentation faster and more reliably for everyone.

For full details, refer to the default target selection documentation and the targets list configuration guide.

Tags:

docs.rs to Reduce Default Build Targets Starting May 2026

Understanding the Change

How the Default Target Is Chosen

Building for Additional Targets

What This Means for Your Crates

Related Articles

Recommended

Discover More