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

Overview of the Change

Starting on May 1, 2026, docs.rs will update its default documentation build behavior. Instead of automatically building documentation for five default targets, the service will now build for only a single target unless you explicitly request additional ones. This adjustment marks the next phase of a policy first introduced in 2020, which allowed crate authors to opt into building fewer targets.

Why This Change Matters

Most Rust crates do not contain platform-specific code; they compile identically across different operating systems and architectures. Building documentation for multiple targets in such cases wastes resources and extends build times. By reducing the default to one target, docs.rs can operate more efficiently, saving valuable compute time and storage. This benefits both the service and the community, as faster builds mean quicker updates and a smaller carbon footprint.

The change only applies to new releases and rebuilds of old releases triggered after May 1, 2026. Existing documentation remains unaffected.

How the Default Target Is Determined

If you do not specify a default-target in your docs.rs metadata, the system will use x86_64-unknown-linux-gnu—the target of the build servers. You can easily override this by setting a different default target in your Cargo.toml:

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

This option gives you full control over the primary target used when no explicit target list is provided.

Configuring the Default Target

To change the default target, add the default-target key under [package.metadata.docs.rs] as shown above. This setting only takes effect if you do not define a targets list.

Building Documentation for Extra Targets

If your crate truly needs documentation for multiple platforms—for example, because it contains conditional compilation or platform-specific APIs—you must now explicitly list all desired targets. This is done using the targets key in your Cargo.toml’s docs.rs 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 present, docs.rs will build documentation for exactly those targets, ignoring the default-target setting. You can include any target that the Rust toolchain supports—only the default behavior is narrowing.

Migration Steps for Crate Maintainers

• Review your crate: Check if your crate uses conditional compilation (#[cfg(...)]) or platform-specific dependencies. If not, you likely don’t need multiple targets.
• If you do need multiple targets: Add the targets list to your Cargo.toml before May 1, 2026.
• If you want a different single target: Set default-target as described above.
• If you are fine with the Linux default: No action required; your crate will continue to build for x86_64-unknown-linux-gnu.

Benefits of the New Default

This simplification reduces the load on docs.rs servers, leading to faster build queues and lower latency for documentation updates. It also encourages crate authors to be more intentional about the platforms they support, potentially catching missing platform-specific documentation earlier. The change aligns with the broader Rust ecosystem’s move toward efficiency and sustainability.

What Remains Unchanged

All existing documentation stays put. The change only influences how future builds are processed. The full range of Rust toolchain targets remains available—you can still request any target you need. The only difference is that you must now be explicit.

For most crates, this adjustment will be transparent. If you have already opted into fewer targets via the 2020 feature, nothing changes for you. If you haven’t, you may notice a reduction in the number of target tabs shown on your crate’s docs.rs page.

Frequently Asked Questions

Will my existing documentation be removed for non-default targets?

No. Documentation already built for multiple targets will remain accessible. Only new builds will be affected.

What if I forget to update my Cargo.toml?

After May 1, 2026, any release without an explicit targets list will only have documentation built for the default target (or your custom default-target). You can always trigger a rebuild later with an updated configuration.

How do I check which targets my crate currently builds for?

Visit your crate’s docs.rs page and look at the target selector dropdown (if present). Or inspect the build logs on docs.rs for the most recent build.

Take Action

If your crate requires documentation on multiple platforms, update your Cargo.toml before May 1, 2026. For most crates, the new default will be a welcome improvement—simpler, faster, and greener.