Optimizing docs.rs: Fewer Build Targets by Default Starting May 2026

Starting on May 1, 2026, docs.rs will introduce a significant change to its default build behavior. Instead of building documentation for five separate targets automatically, it will now build for only one target unless you explicitly request more. This adjustment is part of an ongoing effort to streamline resource usage and improve build times, building on a feature first introduced in 2020 that allowed crate authors to opt into fewer targets.

What's Changing?

Currently, if a crate doesn't specify a targets list in its [package.metadata.docs.rs] section, docs.rs builds documentation for a default set of five targets. After May 1, 2026, the default will shrink to just one target — the platform of the docs.rs build servers (x86_64-unknown-linux-gnu). To have documentation built for other targets, you'll need to define them explicitly.

Why This Change?

Most Rust crates don't compile different code for different targets. Building for multiple targets consumes unnecessary compute time and disk space, and can delay publication of new documentation. By reducing the default to a single target, docs.rs:

• Frees up server resources for other crates.
• Speeds up the build pipeline for the majority of releases.
• Aligns default behavior with the actual needs of most crate maintainers.

This change doesn't remove the ability to build for multiple targets — it simply makes the common case more efficient.

Who Is Affected?

The new default applies to:

• New releases of crates uploaded after May 1, 2026.
• Rebuilds of existing releases triggered after that date.

Crates that already define a custom targets list in their metadata will see no change — docs.rs honors your explicit configuration.

How Does docs.rs Choose the Default Target?

If you do not set default-target in your crate's metadata, docs.rs uses x86_64-unknown-linux-gnu — the same architecture as its build servers. This single target is both the most common platform for testing and the one that matches the environment where docs.rs runs.

Overriding the Default Target

You can change the default target used when no targets list is provided. Add this to your Cargo.toml:

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

This setting only matters if the targets list is absent — otherwise, the explicit list takes precedence.

Building Documentation for Multiple Targets

If your crate truly needs documentation for more than one platform — for example, because it uses conditional compilation for different operating systems — you must supply the full list of desired targets explicitly.

Specifying a Custom Target List

In your Cargo.toml under [package.metadata.docs.rs], add:

[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 present, docs.rs builds documentation for exactly those targets — no more, no less. You can include any target that the Rust toolchain supports. Only the default behavior is changing; the underlying capability to handle cross-platform builds remains intact.

What About Legacy Crates?

Crates published before May 1, 2026, that have never set a targets list will be affected only if they are rebuilt after that date. If you want to preserve the old behavior (building the original five targets), you should add an explicit targets list to your metadata before then. Otherwise, a rebuild will use the new single-target default.

This update aligns with docs.rs's long-term goal of providing fast, reliable documentation while respecting Rust's efficiency principles. For the vast majority of crates, the new default is a welcome optimization — and for those that need more, the mechanism is straightforward.