If you publish Rust crates on docs.rs, you’re about to see a quiet but important shift. Starting May 1, 2026, the documentation builder will no longer automatically compile docs for five different targets. Instead, it will build only for the default target unless you explicitly request more. This change, first teased back in 2020, aims to save resources and speed up builds for the majority of crates that don’t need cross‑platform documentation. In this article, we break down the five essential things you need to understand—from why this is happening, to how you can override the new defaults and keep your crate’s docs comprehensive.
1. The Big Switch: Fewer Targets by Default
As of May 1, 2026, docs.rs will change its default build behavior. Currently, when a crate doesn’t specify a targets list in its [package.metadata.docs.rs] section, the builder automatically generates documentation for five targets (e.g., x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, and two i686 variants). After the cutover, only the default target will be built unless you explicitly define a list. This is a breaking change, but only for new releases and rebuilds of old releases—existing documentation remains untouched. The move is part of a gradual evolution that began in 2020, when docs.rs first introduced the option to opt into fewer build targets.
2. Why Fewer Targets Actually Helps Most Crates
Most Rust crates don’t contain target‑specific code. They compile exactly the same documentation regardless of whether you’re on Linux, macOS, or Windows. Building docs for five targets every time a crate is released wastes computing resources and slows down the pipeline for everyone. By reducing the default to a single target, docs.rs can process builds faster, cut server load, and deliver documentation more quickly to users. If your crate uses conditional compilation (cfg attributes) or platform‑specific features, you can still request multiple targets—but for the vast majority, this change is a net win. It aligns with the principle of “sensible defaults” while still allowing full customization when needed.
3. How the Default Target Is Chosen (And How to Change It)
If you don’t set a default-target in your Cargo.toml metadata, docs.rs will use its build server’s native target: x86_64-unknown-linux-gnu. To override this, add the following to your [package.metadata.docs.rs] section:
[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"This tells docs.rs to use that target as the sole default when building documentation. The default-target field is independent of the targets list—it only sets which single target is built when no explicit list is provided. You can set it to any target that the Rust toolchain supports, such as aarch64-unknown-linux-gnu or x86_64-pc-windows-gnu. For more details, see the docs.rs metadata documentation.
4. Building Documentation for Multiple Targets
If your crate truly needs documentation for several platforms—for example, because it exposes platform‑specific APIs or uses conditional compilation—you must now provide an explicit list of targets in your [package.metadata.docs.rs] section:
[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 will build documentation for exactly those targets—no more, no less. This list overrides the default behavior entirely. You can choose any targets available in the Rust toolchain, from standard desktop triples to niche embedded ones. Just keep in mind that each additional target increases build time and resource usage on the docs.rs infrastructure. Only add the ones your crate actually requires.
5. What This Means for Your Existing Crates
The change only applies to new releases and rebuilds of old releases after May 1, 2026. Existing documentation pages remain as they are—they won’t lose any targets. If you have a crate that was built with five targets before the cutoff, those docs stay online. However, if you trigger a rebuild (for example, because you updated the crate’s metadata or corrected a documentation error), the new default will apply. To avoid accidentally dropping targets on a rebuild, make sure your Cargo.toml includes either a default-target or a full targets list before any rebuild request. The docs.rs team recommends checking your configuration now, so you’re not caught off guard when the switch flips.
As Rust continues to mature, small infrastructure changes like this one make the ecosystem leaner and more efficient. By understanding these five points, you can ensure your crate’s documentation remains complete and up‑to‑date after May 1, 2026. Take a few minutes to review your Cargo.toml metadata—your future self (and your users) will thank you.