Starting May 1, 2026, docs.rs will change its default build behavior to reduce the number of targets for which documentation is automatically generated. Currently, if a crate doesn't specify a target list in its metadata, docs.rs builds docs for five default targets. After the change, only the default target (usually the build server's target) will be built unless you explicitly request more. This move, building on a change from 2020 that allowed opting into fewer targets, aims to save resources and shorten build times, as most crates don't vary code across targets. Below, we address common questions about this update.

What is the precise breaking change coming to docs.rs in 2026?

Starting on May 1, 2026, docs.rs will no longer build documentation for a default list of five targets if a crate lacks a targets field in its [package.metadata.docs.rs] section. Instead, it will build only for the default target (the host target of the docs.rs build servers, e.g., x86_64-unknown-linux-gnu, unless you set default-target). This is a breaking change because it reverts the previous multi-target default. Crates that rely on automatic cross-target builds must now explicitly list their desired targets in Cargo.toml or accept the single-target default.

Why is docs.rs making this change?

The change reduces unnecessary builds. Most Rust crates compile identical code across different platforms—they don't use conditional compilation for each target. Building documentation for five targets when only one is needed wastes docs.rs’s compute time, increases build queues, and consumes more storage. The 2020 opt-in for fewer targets proved that the majority of crate authors prefer simpler defaults. By switching the default to a single target, docs.rs aligns its resource consumption with actual usage, making the service more efficient for everyone while still supporting multi-target builds when explicitly requested.

Which documentation builds are affected by this change?

Only new releases and rebuilds of existing releases that occur after May 1, 2026, are affected. Documentation that was already built before that date will remain unchanged. If you trigger a rebuild of a previously published crate, it will follow the new single-target default unless you update your targets list. The change does not retroactively alter existing documentation pages, so your older docs will keep their current target coverage until you publish a new version or force a manual rebuild.

How is the default target chosen for my crate?

If you don't specify a default-target in your crate’s [package.metadata.docs.rs] section, docs.rs uses the target of its own build servers, which is x86_64-unknown-linux-gnu (the standard Linux x86-64 environment). You can override this by setting a different default-target, for example:

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

This target will then be the sole one built unless you add a targets list. Note that the default-target field only controls which single target is used when no targets list is provided; it does not extend the list of targets built.

How do I build documentation for additional targets?

To have docs.rs build documentation for multiple targets, you must explicitly define the full list in your Cargo.toml under [package.metadata.docs.rs] using the targets key. 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 set, docs.rs builds documentation for exactly those targets. This list replaces the old default, so it must include all the targets you want—including the default target if you still want it. You can list any target available in the Rust toolchain; this change only affects the default behavior, not the set of supported targets.

Can I still use any target from the Rust toolchain?

Yes, absolutely. The change only alters the default list of targets built when no targets field is present. The docs.rs service continues to support every target that the Rust toolchain supports. By setting the targets key to an array of target triples, you can build documentation for any combination of platforms, including niche ones like aarch64-unknown-linux-gnu or wasm32-unknown-unknown. The underlying infrastructure remains unchanged—only the set of targets built automatically is reduced to one.

What should I do to maintain the current multi-target behavior?

If your crate currently relies on the default five-target builds and you want to preserve that behavior after May 2026, you need to add an explicit targets list to your Cargo.toml. Copy the five targets previously used by docs.rs into your 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"
]

Alternatively, if you only need one specific target, you can keep the new default or set default-target. The recommendation is to review your crate’s conditional compilation and only build for targets where it actually differs. This saves time and resources on docs.rs while keeping documentation complete where needed.