Docs.rs Streamlines Documentation Builds: Fewer Targets by Default

Starting May 1, 2026, docs.rs is implementing a significant change to its documentation build process. Instead of building for five default targets, it will now build for just one—unless you explicitly request more. This shift, building on a 2020 opt‑in feature, aims to reduce build times and save resources, as most crates produce identical code across different targets. Below, we answer your key questions about what’s changing and how to adapt.

• What exactly is changing?
• Why is docs.rs reducing default targets?
• Who will be affected?
• How is the default target chosen?
• How can I override the default target?
• How do I build for additional targets?
• Can I still use any Rust target?

What exactly is changing with docs.rs builds on May 1, 2026?

Currently, when a crate doesn’t specify a targets list in its [package.metadata.docs.rs] section, docs.rs builds documentation for five predefined targets. After May 1, 2026, the default will be only one target: the build server’s own architecture (x86_64-unknown-linux-gnu). This change applies to all new releases and any rebuilds of old releases. If your crate already sets its own targets list, nothing changes. This is the next step in a policy first introduced in 2020, when docs.rs allowed opting into fewer builds.

Why is docs.rs reducing the default number of build targets?

The vast majority of Rust crates do not compile platform‑specific code across different targets. Building documentation for five targets when only one is needed wastes time and resources. By defaulting to a single target, docs.rs can complete builds faster and allocate its limited compute capacity more efficiently. This change also simplifies the workflow for crate authors who never needed multiple target docs in the first place. Those who do need cross‑target documentation can easily opt back in by specifying their desired targets in Cargo.toml metadata.

Who will be affected by this change?

Only crates that do not define a targets list in their docs.rs metadata will see a difference. If you have already set a custom targets array, your build behavior remains unchanged. Affected crates include those relying on the previous default of five targets—their documentation will now be generated for just one target. Both new releases and rebuilds of existing releases are subject to the new default. No other documentation service or feature is impacted.

How is the default target chosen if I don’t set anything?

If you omit both default-target and targets from your docs.rs metadata, the build system uses its own host architecture: x86_64-unknown-linux-gnu. This is the target of the servers that run docs.rs. You can change this default by adding the default-target field to your [package.metadata.docs.rs] section in Cargo.toml. For example, to default to macOS instead of Linux, set default-target = "x86_64-apple-darwin". This value will be used only if you do not provide an explicit targets list.

How can I override the default target?

To change the single default target that docs.rs builds for, add this to your Cargo.toml:

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

This replaces the server’s default (x86_64-unknown-linux-gnu) with your chosen target. The override only applies when you do not define a full targets list. If you later specify targets, that list takes precedence entirely. This field is optional; it exists to give you a quick way to control the single target without listing all possibilities.

How do I build documentation for additional targets?

If your crate requires documentation for more than one target (e.g., Linux, macOS, and Windows), define the complete list explicitly in your Cargo.toml:

[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—ignoring both the default and any default-target override. This gives you full control over which architectures and platforms your documentation covers.

Can I still use any target available in the Rust toolchain?

Absolutely. The change only affects which targets are built by default. docs.rs continues to support every target that the Rust compiler supports—from wasm32-unknown-unknown to aarch64-apple-ios. You can list any valid Rust triple in the targets array. The only difference is that you now need to explicitly request additional targets; the system no longer provides a multi‑target default. This adjustment helps docs.rs operate more efficiently while still giving you the flexibility to document your crate for any platform.