Starting May 1, 2026, docs.rs is implementing a significant change in its default build behavior. Up until now, if a crate didn't define a specific list of targets in its docs.rs metadata, the service would automatically generate documentation for five default targets. After that date, only a single target will be built by default—unless crate authors explicitly request additional ones.

This change represents the next logical step in a process that began back in 2020, when docs.rs first allowed opt-in for reducing the number of build targets. The vast majority of Rust crates do not contain platform-specific code that requires different documentation for each target. Therefore, building fewer targets by default is a more efficient approach for most releases, reducing build times and conserving computational resources.

Why This Change Is Happening

docs.rs has always aimed to provide comprehensive documentation for the Rust ecosystem. However, building documentation for five targets—x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, i686-unknown-linux-gnu, and i686-pc-windows-msvc—consumes significant server time and storage. Many crates ship identical code for all these targets, so the resulting documentation is identical across platforms. By moving to a single default target, docs.rs can allocate resources more efficiently, speed up builds, and reduce the environmental footprint of its operations.

This change also aligns with the principle of you only pay for what you use. If your crate genuinely needs multi-target documentation, you can still opt in; otherwise, you and the docs.rs infrastructure both benefit from a leaner default.

What Does This Mean for Your Crates?

If your crate does not set a targets list in its package.metadata.docs.rs section, after May 1, 2026, docs.rs will build documentation only for the default target (typically x86_64-unknown-linux-gnu). This applies to:

• New releases published after the cutover date.
• Rebuilds of existing releases initiated via the docs.rs interface.

Existing documentation generated before May 1 will remain unaffected. Only future builds will follow the new policy.

When You Must Define Targets Explicitly

If your crate contains platform-specific code—such as conditional compilation with cfg attributes—that results in different documentation for different targets, you must define the full list of targets in your Cargo.toml. Otherwise, users on non-default platforms may see incomplete or missing documentation.

How the Default Target Is Determined

If you do not specify a default-target in your docs.rs metadata, the default target is x86_64-unknown-linux-gnu—the architecture and operating system of docs.rs’s own build servers. You can override this by setting the default-target field:

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

This will make x86_64-apple-darwin the single target built when no explicit targets list is provided. However, note that only one target will be built; if you need more than one, you must use the targets array (see below).

How to Configure Additional Targets

To have docs.rs build documentation for multiple targets, define the complete list in your Cargo.toml under package.metadata.docs.rs:

[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 the targets array is present, docs.rs will build documentation for exactly those targets—no more, no less. You can include any target that the Rust toolchain supports (e.g., armv7-unknown-linux-gnueabihf, wasm32-unknown-unknown). Only the default behavior is changing; the support for custom target lists remains unchanged.

Tip: If your crate uses platform-specific features but you are unsure which targets to include, review your cfg directives or consult common Rust target triples used by your users.

Important Dates and Impact

The new default behavior takes effect on May 1, 2026. After that date, any crate that does not explicitly set a targets list will have its documentation built for a single target only. This change applies to:

• New crate versions published on or after May 1, 2026.
• Manual rebuilds of older releases triggered from the docs.rs interface.

Existing documentation hosted on docs.rs will remain unchanged. Users browsing older versions will still see the full multi-target documentation that was built before the cutover.

We encourage all crate authors to review their Cargo.toml metadata before the deadline. If your crate needs documentation on multiple platforms, add an explicit targets list. If it does not, you can safely rely on the new default and enjoy faster builds.

For more details, refer to the docs.rs metadata documentation and the RFC that introduced this change.