Docs.rs Default Build Targets: What's Changing and How to Prepare

Starting on May 1, 2026, docs.rs will change its default build behavior to build documentation for only one target instead of five. This change, first hinted at in 2020, aims to reduce build times and save resources since most crates don't vary code across platforms. Below, we answer common questions about the update, how it affects you, and how to adjust your crate configuration.

What is changing about docs.rs build behavior?

Currently, if a crate doesn't specify a list of targets in its docs.rs metadata, the service builds documentation for five default targets. Starting May 1, 2026, docs.rs will instead build solely for the default target (typically x86_64-unknown-linux-gnu) unless you explicitly request additional targets. This is a breaking change that only applies to new releases and rebuilds of old releases. Older documentation built before the cutoff remains unaffected.

When does this change take effect?

The new default behavior goes live on May 1, 2026. Crate maintainers should review their configurations before that date to ensure their documentation still meets their needs. If you rely on multi‑target docs, you'll need to update your Cargo.toml metadata before publishing any new releases after that date.

Why is docs.rs making this change?

Building five targets by default is unnecessary for the vast majority of crates—most don't compile platform‑specific code. By switching to a single default target, docs.rs will reduce build times and conserve resources on its servers. This change also aligns with the platform's 2020 introduction of opt‑in target selection, giving maintainers more control over which platforms their docs are built for.

How is the default target chosen?

If you don't set default-target in your crate's docs.rs metadata, docs.rs will use the build server's own target: x86_64-unknown-linux-gnu. You can override this by adding the following to your Cargo.toml:

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

This setting tells docs.rs which single platform to build for when no explicit target list is provided.

How can I build documentation for additional targets?

To build for more than just the default target, you must define the full list explicitly in your Cargo.toml using the targets key:

[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 exactly those targets and ignores the default. You can include any target available in the Rust toolchain.

Who is affected by this change?

This change impacts new releases and rebuilds of old releases after May 1, 2026. Existing documentation built before that date stays as is. Crate maintainers who already use targets or default-target metadata will see no difference. Only those relying on the current implicit list of five default targets will need to update their configuration if they want to continue building for multiple platforms.

Can I still use any target I want?

Yes, absolutely. The change only alters the default behavior. You can still request any target that the Rust toolchain supports—docs.rs has not removed any platform options. To build for a non‑default set of targets, simply list them in the targets array as described above. The flexibility remains; only the fallback list is being reduced.