10 Crucial Updates About docs.rs Build Target Changes Starting May 2026

If you publish Rust crates on crates.io, docs.rs is about to change how it builds documentation. Starting May 1, 2026, the platform will stop building documentation for five default targets and instead build only for a single default target. This move aims to save resources and speed up builds, but it means you may need to update your crate's metadata to ensure your documentation covers the platforms your users rely on. Below are ten essential facts every crate maintainer should know about this upcoming change.

1. The Breaking Change Date: May 1, 2026

On May 1, 2026, docs.rs will alter its default build behavior. Currently, if you don't specify a target list in your [package.metadata.docs.rs], docs.rs builds documentation for five predetermined targets. After that date, only the default target will be built unless you explicitly request additional ones. This is a breaking change that could affect how your documentation appears across different platforms.

2. Current Default: Five Targets

As of now, docs.rs builds documentation for five targets by default: x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, i686-unknown-linux-gnu, and i686-pc-windows-msvc. This comprehensive set was intended to cover the most common desktop environments, but it turns out most crates don't have platform-specific code. Building for all five wastes time and server resources.

3. New Default: Single Target

Starting May 2026, the default behavior will build documentation for only one target: x86_64-unknown-linux-gnu (unless you override the default target). This change aligns with the fact that the vast majority of crates compile identical code regardless of the target. If your crate uses conditional compilation or platform-specific APIs, you'll need to explicitly list the targets you want. See item 6 for how the default target is chosen and item 8 for adding more.

4. Why the Change? Efficiency and Resource Savings

This decision continues a trend that started in 2020 when docs.rs added the ability to opt into fewer targets. Building fewer targets by default reduces the load on docs.rs servers, cuts build times for most releases, and minimizes unnecessary duplication. Since most crates have identical documentation across platforms, this change is a logical step toward a more efficient ecosystem.

5. Which Releases Are Affected?

The new default applies only to new releases and rebuilds of old releases that occur after May 1, 2026. Existing documentation that was built before the cutoff will remain unchanged. If you don't publish new versions of your crate, your existing docs will stay as they are. However, any trigger (like a new release or a forced rebuild) will cause the new default to take effect.

6. How the Default Target Is Determined

If you don't set default-target in your docs.rs metadata, the default target is x86_64-unknown-linux-gnu (the architecture of docs.rs build servers). You can change this by setting default-target in Cargo.toml under [package.metadata.docs.rs]. For example, default-target = "x86_64-apple-darwin" will make macOS the primary platform for your docs.

7. Overriding the Default Target

To change the default target, add this to your Cargo.toml:

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

This overrides the automatic selection of x86_64-unknown-linux-gnu and ensures your documentation is built for that target by default. Note that setting default-target does not add extra targets; it only changes which single target is built when no targets list is provided.

8. Building Documentation for Multiple Targets

If your crate needs documentation on more than one target (e.g., because of conditional compilation), define the full 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 documentation for exactly those targets, ignoring the default. You can include any target that Rust supports.

9. Full List of Supported Targets

docs.rs continues to support any target available in the Rust toolchain. Only the default set is shrinking. You can still request uncommon targets (like aarch64-linux-android or wasm32-unknown-unknown) in your targets array. The change affects only crates that rely on the implicit default list.

10. Backward Compatibility and Migration Steps

To avoid surprises, review your crate's docs.rs metadata before May 2026. If you already have a targets list, nothing changes. If you rely on the default five targets and want to preserve them, simply copy the default list into your Cargo.toml. Otherwise, your docs will be built for a single target. This change is backward compatible in the sense that existing builds remain untouched, but new builds will follow the new default.

In summary, the upcoming docs.rs adjustment simplifies the build process for most crates while saving resources. By understanding these ten points, you can ensure your documentation remains comprehensive across the platforms your users need. Take a moment to update your configuration, and you'll be all set for May 1, 2026.