Docs.rs Default Build Targets: Upcoming Changes and How to Adapt

Starting May 1, 2026, docs.rs will implement a significant change in how it builds documentation by default. Previously, if a crate didn't specify a targets list in its docs.rs metadata, the system would build documentation for five default targets. Now, only the default target will be built unless additional targets are explicitly requested. This shift builds on an option introduced in 2020 that allowed opting into fewer build targets. Since most crates don't vary code across targets, this new default saves resources and reduces build times. Below, we answer common questions about this change.

What is changing in docs.rs default build behavior?

As of May 1, 2026, docs.rs will no longer build documentation for a default list of five targets when a crate lacks a targets list in its Cargo.toml metadata. Instead, documentation will be built for only one target—the default target (typically x86_64-unknown-linux-gnu). This is a breaking change from the current behavior. Crates that previously relied on the five-target default will need to explicitly list their desired targets to maintain multi-platform documentation. The change applies only to new releases and rebuilds of old releases; existing documentation remains unaffected.

Why is docs.rs making this change?

The primary motivation is efficiency. Most Rust crates compile identical code regardless of the target platform—differences like operating system or architecture rarely affect the documented API. Building documentation for multiple targets when it's unnecessary consumes significant server resources and lengthens build times. By shifting to a single-target default, docs.rs can reduce its computational load and deliver documentation faster. This change is the next step in a gradual transition that began in 2020, when support for opting into fewer targets was added. For the majority of crate authors, the new default will have no practical impact on their users.

When will this change take effect?

The change is scheduled for May 1, 2026. After that date, any new crate release or rebuild of an old release (triggered by a maintainer or by docs.rs) will use the new single-target default. Crate authors have until that date to update their metadata if they need multiple targets. The exact timing may be adjusted, but docs.rs has announced this date well in advance to give the community time to adapt.

Which releases are affected by this change?

The change affects only new releases and rebuilds of old releases. Releases that were documented before May 1, 2026, will retain their existing multi-target documentation unless they are explicitly rebuilt. If a maintainer triggers a rebuild for an older release after the cutoff, that rebuild will use the new default. Documentation that remains untouched will stay as-is. In practice, the impact is limited to crates that haven't configured a targets list—those with an explicit list will continue to build exactly as before.

How is the default target chosen if not specified?

If you do not set default-target in your [package.metadata.docs.rs] section, docs.rs uses the target of its build servers: x86_64-unknown-linux-gnu. This is a Linux x86-64 architecture. To override this, you can set the default-target key to any Rust target triple (e.g., x86_64-apple-darwin for macOS). The chosen target becomes the sole platform for which documentation is built unless you also specify an explicit targets list. Note that this setting only matters if you don't define a full targets list—if you do, the default-target is ignored.

How can I override the default target?

To change the default target, add a default-target field inside the [package.metadata.docs.rs] section of your Cargo.toml. For example:

[package.metadata.docs.rs]
default-target = "x86_64-pc-windows-msvc"

This will make docs.rs build documentation for Windows MSVC on x86_64 by default. However, if you also define a targets list, the default-target is ignored in favor of that list. The override is useful if you want to change the single target that gets built without listing all targets explicitly.

How do I build documentation for additional targets?

If your crate's API varies across platforms and you need documentation for multiple targets, you must list them explicitly in your Cargo.toml. Add a [package.metadata.docs.rs] section with a targets array containing the desired Rust target triples. For example:

[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 and ignores the default-target field. This list can include any target available in the Rust toolchain, from ARM platforms to BSD systems. You can also include fewer than five targets—the old default list is no longer used. We recommend reviewing your crate's conditional compilation to determine which targets are truly necessary.

Does docs.rs still support all targets?

Yes, absolutely. The change only alters the default behavior when no targets list is provided. Docs.rs continues to support any Rust target that exists in the toolchain. If you explicitly list targets—whether one or fifty—they will all be built. The limitation is that without an explicit list, only one target (the default) will be used. This means the full flexibility of multi-target documentation remains available; you just need to opt in by configuring your metadata. So if your crate benefits from platform-specific documentation, simply define your targets list and nothing is lost.