Overview

On May 1, 2026, docs.rs will implement a significant change to its build behavior. Currently, if a crate doesn't define a targets list in its docs.rs metadata, the platform builds documentation for a fixed set of five default targets. After this date, only the default target will be built unless you explicitly request additional targets. This adjustment builds on a change first introduced in 2020, when docs.rs allowed opting into fewer targets. The rationale is straightforward: most crates compile the same code across all targets, so building fewer targets by default reduces build times, conserves resources, and aligns better with typical usage. Note that this change only affects new releases and rebuilds of old releases—it does not retroactively alter existing documentation.

Prerequisites

• A Rust crate with a Cargo.toml file.
• Familiarity with [package.metadata] sections in Cargo.toml.
• Basic understanding of target triples (e.g., x86_64-unknown-linux-gnu).
• Access to your crate's repository to modify configuration.

Step-by-Step Instructions

Understanding the Change

Before diving into configuration, it's crucial to grasp what's happening. As of May 1, 2026, docs.rs will no longer automatically build documentation for five targets. Instead, it will build only for the default target (typically x86_64-unknown-linux-gnu). If your crate relies on platform-specific code (e.g., conditional compilation with #[cfg(target_os = "windows")] or different architectures), you must explicitly list the targets for which you want documentation built. This change applies regardless of whether you're publishing a new version or triggering a rebuild of an older release.

How the Default Target is Selected

If you do not set the default-target key in your docs.rs metadata, docs.rs will use the build server's native target: x86_64-unknown-linux-gnu. To override this, add the following to your Cargo.toml:

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

This tells docs.rs to build documentation for that target on the default build (and also use it as the fallback when no targets list is provided).

How to Build Documentation for Additional Targets

If your crate needs documentation for more than one target, define the complete list explicitly in the [package.metadata.docs.rs] section of your Cargo.toml. For example:

[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 set, 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., aarch64-unknown-linux-gnu, wasm32-unknown-unknown). Remember: the default-target setting is ignored if you provide a targets list; the list fully specifies what gets built.

Checking Your Current Configuration

To verify whether your crate will be affected, examine your Cargo.toml for any existing [package.metadata.docs.rs] section. If it lacks a targets list, your crate currently relies on the old default (five targets). After the change, only the default target will be built unless you add the list. You can test your configuration by triggering a dry-run on docs.rs (not currently available) or by reviewing the documentation for a recent release to see which targets were built.

Common Mistakes

• Omitting the default target from the list: If you specify a targets list, make sure it includes the target you want as the default (e.g., x86_64-unknown-linux-gnu). Otherwise, that target won't be built.
• Assuming the old default list persists: Starting May 1, 2026, the five-target default no longer applies. You must explicitly list any target beyond the default.
• Forgetting to update metadata for old releases: If you trigger a rebuild of an older release after the change, it will also follow the new rules. Update the targets list in the tag's Cargo.toml before requesting a rebuild.
• Using default-target alone for multiple targets: The default-target key only sets the primary target; it does not add other targets. Use the targets list for multiple.
• Not verifying conditional compilation: If your crate has platform-specific code, ensure all relevant targets are in the list. Missing a target means missing documentation for that platform's users.

Summary

The upcoming change to docs.rs default build targets reduces resource usage and aligns with typical crate behavior. By May 1, 2026, only the default target (x86_64-unknown-linux-gnu by default) will be built unless you explicitly list all desired targets in your Cargo.toml under [package.metadata.docs.rs]. To ensure your crate's documentation remains comprehensive, review your configuration, add a targets list if needed, and remember to include the default target. This adjustment will affect all new releases and rebuilds, so take action before the deadline.