docs.rs Streamlines Builds: Default Targets Reduced Starting May 2026

On May 1, 2026, docs.rs will implement a significant change to its default build behavior. Currently, unless a crate explicitly defines a targets list in its metadata, docs.rs builds documentation for five default targets. After the change, only the default target will be built unless additional targets are requested. This update aims to improve efficiency and reduce resource usage, aligning with the needs of most crate authors.

Why This Change?

The decision to reduce the default number of build targets stems from a 2020 initiative that introduced the ability to opt into fewer targets. The vast majority of Rust crates do not compile platform-specific code, meaning building documentation for five targets is often unnecessary. By defaulting to a single target, docs.rs will:

• Decrease build times for new releases.
• Save server resources, allowing faster turnaround for all crate documentation.
• Simplify the default experience for crate authors who don't need multi-target documentation.

This change reflects the principle that defaults should match the common use case, while still offering full flexibility for those who need it.

Who Is Affected?

The new behavior will apply exclusively to:

• New releases of crates (including yanks and re-publishes).
• Rebuilds of existing releases triggered by infrastructure changes.

Already published documentation will remain untouched. If you do not update your crate or request a rebuild, your existing multi-target docs will stay unchanged.

How Is the Default Target Chosen?

If you do not specify a default-target in your docs.rs metadata, the system will use x86_64-unknown-linux-gnu — the same architecture as docs.rs build servers. However, you can override this value by setting it in your Cargo.toml:

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

This single target will be used for the main documentation build, and it also serves as the fallback platform for features like doc(cfg) attributes.

Overriding the Default Target

To change the default target, add the default-target key inside the [package.metadata.docs.rs] section. The value must be a valid Rust target triple (e.g., aarch64-unknown-linux-gnu). This is especially useful if your crate is primarily used on a different platform, such as macOS or Windows.

How to Build Documentation for Additional Targets

If your crate contains platform-specific code (for example, using conditional compilation with #[cfg(target_os = "windows")]), you may need documentation for multiple targets. Starting May 1, 2026, you must explicitly declare the full list of desired targets 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 will build documentation for exactly those targets — no more, no less. The system continues to support every target available in the Rust toolchain, but you must opt in explicitly. This change does not remove any existing functionality; it only alters the default behavior.

Migrating from the Old Default

If your crate previously relied on the five-default-target list, you can replicate that by copying the example above into your Cargo.toml. Alternatively, you can minimize your target list to only those platforms your crate actually supports, potentially reducing build time further.

Timeline and Next Steps

1. Before May 1, 2026: Review your crate's documentation needs. If you require multiple targets, update your Cargo.toml with the explicit targets list.
2. On May 1, 2026: The new default takes effect. Any new release without a targets definition will build only the default target.
3. After the change: You can still request a rebuild of an older release to apply the new behavior, but it will only build the default target unless you supply a targets list in your metadata.

For most crate authors, this change will be transparent and beneficial. By focusing resources on what matters most, docs.rs can deliver faster documentation updates and a leaner overall platform.