Docs.rs Default Build Targets Are Changing: What You Need to Know

Overview of the Change

Starting May 1, 2026, docs.rs will modify its default build behavior. Currently, when a crate does not specify a list of targets in its documentation metadata, the service builds documentation for five default targets. After the change, only documentation for the default target will be built unless additional targets are explicitly requested. This is a continuation of a policy first introduced in 2020, which allowed crate authors to opt into building fewer targets.

Why This Change?

Most crates contain platform-agnostic code that compiles identically across targets. Building documentation for multiple targets in those cases is unnecessary and wastes resources. By defaulting to a single target, docs.rs will:

• Reduce build times for the majority of crates
• Save computing resources on the docs.rs infrastructure
• Provide a better fit for typical usage patterns

This adjustment aligns with the original 2020 opt-in model, making it the new standard.

Which Releases Are Affected?

The change applies to:

• New releases published after May 1, 2026
• Rebuilds of existing releases triggered after that date

Previously built documentation will remain unchanged until a rebuild occurs.

How Is the Default Target Chosen?

If you do not define a default-target in your crate’s metadata, docs.rs will use x86_64-unknown-linux-gnu, the same target running on its build servers. To override this, add the following to your Cargo.toml:

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

This setting determines which target is built when you rely on the default behavior.

How to Build Documentation for Additional Targets

If your crate requires documentation for more than one target (e.g., cross-platform APIs or conditional compilation), you must explicitly list all desired targets using the targets key:

[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 list is present, docs.rs will build documentation for exactly those targets (no more, no less). This list replaces the default set entirely.

Combining default-target and targets

You can set both default-target and targets. In that case, default-target is used only when no targets list is provided. If you specify targets, the default-target is ignored for the purpose of the build list. However, you may include the default-target value as one of the entries in the targets array if desired.

Backward Compatibility and Flexibility

This change only alters the default behavior. All targets previously supported by the Rust toolchain are still available. Crate authors who already defined a targets list will see no difference. The update is designed to reduce unnecessary builds while giving full control to those who need it.

Recommendations for Crate Authors

To ensure your documentation continues to be built correctly:

1. Check your crates for conditional compilation that differs across targets (e.g., cfg(unix) or cfg(windows)).
2. If you need multiple target builds, add the targets list to your Cargo.toml before the deadline.
3. Consider setting a default-target if your primary audience uses a different platform than Linux (for instance, macOS or Windows).

For most crates that are platform-agnostic, the new single-target default will work perfectly and speed up documentation generation.

Summary

The May 1, 2026 change on docs.rs reduces the default number of build targets from five to one. This saves resources and shortens build times. Crate authors can opt into more targets by defining the targets list, or change the default target via the default-target setting. Plan ahead to avoid any disruption in your documentation builds.

For further details, see the default target section or how to add additional targets.