docs.rs Adjusts Default Build Targets: What You Need to Know

By • min read

What’s Changing?

As of May 1, 2026, docs.rs will implement a significant change in how it builds documentation for Rust crates. Currently, if a crate does not explicitly specify a list of targets in its docs.rs metadata, the system automatically builds documentation for five default targets. After this date, docs.rs will build documentation for only the default target unless additional targets are explicitly requested. This adjustment is the latest step in a process that began in 2020, when docs.rs first introduced the ability for crate authors to opt into building fewer targets.

This change applies exclusively to new releases and rebuilds of old releases. Existing documentation remains unaffected.

Why the Shift?

The rationale behind this change is straightforward: most crates do not compile different code for different targets. For the majority of releases, building documentation for multiple targets is unnecessary and consumes extra time and resources. By reducing the default build targets, docs.rs can shorten build times, conserve server resources, and provide a more efficient experience for both crate authors and users. The change aligns with the principle of optimizing defaults for the common case.

Default Target Selection

If you do not specify a default-target in your docs.rs metadata, the system will automatically use the architecture of its build servers. Currently, that target is x86_64-unknown-linux-gnu. This is the same target used for most Rust builds on standard Linux environments.

Customizing the Default Target

You can override the default target by adding a default-target key in your docs.rs metadata within Cargo.toml. For example:

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

This tells docs.rs to use a different default target, such as macOS, instead of the server’s native Linux target.

Building for Additional Targets

If your crate requires documentation to be built for more than just the default target, you must define the complete list of targets explicitly. Use the targets array in your 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 you set the targets field, docs.rs will build documentation for exactly those targets, ignoring any default list. This gives you full control over which platforms are covered.

What About Other Targets?

docs.rs continues to support any target that is available in the Rust toolchain. Only the default behavior is changing; the system still allows you to request builds for any target you need. If your crate relies on platform-specific behavior—such as inline assembly, conditional compilation with cfg, or OS-specific APIs—you should explicitly list those targets to ensure complete documentation coverage.

Impact and Next Steps

This change is a breaking change only for crates that depend on the previous default of five targets but have not explicitly configured them. For most crate authors, the impact will be minimal because single-target builds already meet their needs. However, if your crate targets multiple architectures or operating systems, you should:

• Review your current docs.rs metadata settings.
• If you already use the targets field, no action is needed.
• If you rely on the old defaults, add an explicit targets list before May 1, 2026, to maintain multi-target documentation builds.

The docs.rs team recommends updating your Cargo.toml as soon as possible to avoid any disruption to your documentation builds. For more details, see the official Rust documentation on multiple targets.

By making this change, docs.rs continues to evolve toward a more efficient and developer-friendly service. The shift to building fewer targets by default reflects both community input and practical usage patterns, ensuring that resources are used where they matter most.