Docs.rs Streamlines Documentation Builds: Default Targets Reduced to One

By ✦ min read

Upcoming Change to Default Build Behavior

On May 1, 2026, docs.rs will implement a significant update to its default documentation build process. This change simplifies the current system, where documentation is built for five different targets by default, to a more efficient single-target approach. This adjustment builds on a feature first introduced in 2020 that allowed users to opt into fewer build targets.

For most crates, the codebase remains consistent across different compilation targets. Therefore, building documentation for multiple targets often results in duplicated effort and wasted resources. By defaulting to just one target, docs.rs can reduce build times and server load without impacting the vast majority of users. This update applies exclusively to new releases and rebuilds of existing releases initiated after the cutover date.

How the Default Target Is Determined

If a crate does not explicitly specify a default-target, docs.rs will use its own build server's architecture: x86_64-unknown-linux-gnu. To override this, add the default-target field under [package.metadata.docs.rs] in your Cargo.toml file. For example:

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

How to Build Documentation for Additional Targets

If your crate requires documentation for more than one target, you must explicitly list all desired targets using the targets array in the same metadata section. When targets is set, docs.rs will build documentation for exactly those targets. Here's an example that mirrors the previous default set:

[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"
]

This mechanism supports any target available in the Rust toolchain. The only change is the default behavior—if you do nothing, only one target will be built after the cutoff date.

Preparing Your Crates for the Transition

To ensure your documentation remains comprehensive after May 1, 2026, consider the following steps:

• If you rely on the current default set, add the targets list to your Cargo.toml now. The example above preserves the old behavior.
• If you only need documentation for one or two targets, set default-target to your preferred platform.
• If your crate is target-independent, you can do nothing—the single-target default will work fine.

Remember that this change does not remove the ability to build for multiple targets; it only modifies the default selection. By explicitly specifying your needs, you keep full control over your documentation output.

For more details, refer to the default target and additional targets sections above. This update helps docs.rs operate more efficiently while continuing to serve the Rust community effectively.