Docs.rs Default Build Targets: What’s Changing and How to Adapt

By — min read

On May 1, 2026, docs.rs will update its default behavior for building documentation across multiple targets. Currently, if a crate doesn’t specify a targets list in its docs.rs metadata, documentation is built for five default targets. Starting May 1, only the default target will be built unless you explicitly request additional ones. This change builds on an opt-in system introduced in 2020. Since most crates don’t vary code by target, this shift saves resources and speeds up builds. The update affects only new releases and rebuilds of old ones—not existing documentation. Below, we answer key questions to help you adapt.

What is changing with docs.rs default build targets?

Starting May 1, 2026, docs.rs will reduce the number of targets built by default from five to one. Previously, if a crate didn’t define a targets list in its [package.metadata.docs.rs] section, docs.rs would build documentation for x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, i686-unknown-linux-gnu, and i686-pc-windows-msvc. After the change, only the default target (typically x86_64-unknown-linux-gnu) will be built unless you specify otherwise. This is a breaking change, so crates relying on the old default list may need updates.

Docs.rs Default Build Targets: What’s Changing and How to Adapt — Source: blog.rust-lang.org

When will this change take effect?

The change goes live on May 1, 2026. It applies to all new crate releases uploaded after that date, as well as any manual rebuilds of older releases. Documentation already published before May 1 remains unaffected—only fresh builds will follow the new default. If you need to rebuild an existing release after the deadline, you’ll need to update your Cargo.toml to include the desired targets.

Why is docs.rs making this change?

The primary reasons are efficiency and resource conservation. Most Rust crates do not compile conditionally for different targets—their documentation is identical across platforms. Building for five targets by default was wasteful, increasing build times and consuming server resources unnecessarily. By switching to a single default target, docs.rs reduces its workload and speeds up documentation generation for the majority of releases. This change continues the path started in 2020 when they first allowed opting into fewer targets. For crates that genuinely need multi-target docs, the explicit configuration option remains available.

How is the default target chosen?

If you don’t set a default-target in your docs.rs metadata, docs.rs automatically uses x86_64-unknown-linux-gnu, which matches its build servers. You can override this by adding the following to your Cargo.toml:

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

This setting changes only the single target used when no explicit targets list is provided. It does not enable building multiple targets; for that, you need to define a full list under targets.

How can I build documentation for additional targets?

To have docs.rs build docs for multiple targets, define the complete list explicitly in your Cargo.toml under [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 builds documentation for exactly those targets, overriding the default. You can include any target available in the Rust toolchain. This approach gives you full control and ensures your docs appear on all platforms your crate supports.

Which releases are affected by this change?

The change applies exclusively to:

New releases uploaded on or after May 1, 2026.
Rebuilds of old releases triggered after that date.

Existing documentation published before the deadline remains unchanged. If you never rebuild an older release, its multi-target docs will persist. However, if you later request a rebuild—for example, to fix a broken doc—the new default will apply, and you may lose target coverage unless you update your configuration.

What if my crate already defines a targets list?

If your Cargo.toml already contains a [package.metadata.docs.rs] targets list, this change does nothing to you. Docs.rs will continue to use that explicit list, ignoring the default. No action is required. Crates that currently rely on the old default list (i.e., they have no targets set and expect five builds) should add a targets list before May 1 to maintain the same coverage. For crates that are happy with just one target, no change is needed.

Tags: