Overview of the Upcoming Change

Starting May 1, 2026, docs.rs will alter its default build behavior. Currently, when a crate does not specify a targets list in its docs.rs metadata, the system builds documentation for five default targets. After the change, only the default target will be built unless additional targets are explicitly requested. This marks the next phase of an optimization first introduced in 2020, which gave crate authors the ability to opt into fewer build targets.

This adjustment is better suited for the vast majority of crates, as most do not compile different code for different targets. Reducing the number of default builds speeds up documentation generation and conserves resources on docs.rs servers. The modification applies only to new releases and rebuilds of existing releases after the effective date; previously built documentation remains unaffected.

How the Default Target Is Chosen

If your crate’s metadata does not include a default-target setting, docs.rs will automatically use the architecture of its build servers—specifically, x86_64-unknown-linux-gnu. To override this, you can set a different default target inside your Cargo.toml under the [package.metadata.docs.rs] section:

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

This simple change tells docs.rs to generate documentation for that specific platform when no explicit targets list is provided.

Building Documentation for Multiple Targets

If your crate requires documentation for more than just the default target, you must explicitly define the complete list. Add a targets array to the [package.metadata.docs.rs] section of 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. Note that you are not limited to these five; any target available in the Rust toolchain is supported. Only the default behavior changes—you retain full control over which architectures appear in your crate’s documentation.

Who Is Affected and How to Prepare

This change impacts all crate maintainers who rely on the default multi-target build. If your crate does not currently specify a targets list, after May 1, 2026, only one target will be built. For most crates, this is sufficient, but if you depend on documentation for other platforms, you need to update your Cargo.toml before the cutoff date.

Review your crate’s documentation needs and decide whether the default target covers your user base. If you serve multiple platforms, add an explicit targets list. Doing so ensures continuous and correct documentation generation without interruption.

We recommend testing the new configuration in a development environment or on a pre-release version of your crate. Once you’re satisfied, the updated metadata will take effect for all subsequent releases.

Frequently Asked Questions

Will existing documentation be removed?

No. Documentation already built for previous releases remains online. The change only affects builds started after the effective date.

Can I still get documentation for all targets?

Yes. The targets list allows any combination of Rust’s supported targets. The default is simply reduced to one.

How do I know my current default target?

If you haven’t set default-target, it will be x86_64-unknown-linux-gnu. You can check by inspecting your crate’s build logs or metadata.

For further details, consult the docs.rs documentation or visit the project’s issue tracker. This change aligns with the ongoing effort to make resource usage more efficient while giving maintainers precise control over their documentation output.