Docs.rs to Streamline Default Builds: Fewer Targets by Default from May 2026

Starting May 1, 2026, docs.rs will implement a significant change to its default build behavior. Instead of building documentation for five default targets as it does today, docs.rs will generate docs for only the primary target unless additional targets are explicitly requested via crate metadata. This adjustment builds on a 2020 feature that allowed crate authors to opt into building fewer targets. For the majority of crates that don't vary code across platforms, this default reduction means faster builds, lower resource consumption, and a more efficient service. This change applies only to new releases and rebuilds of existing releases. Below, we answer common questions about how this affects your crates and how to adapt.

What exactly is changing in docs.rs default build behavior?

Currently, when a crate lacks a targets list in its docs.rs metadata, the system automatically builds documentation for a default set of five targets. As of May 1, 2026, that default will shrink to just one target: the default target of the docs.rs build servers (x86_64-unknown-linux-gnu). To get documentation for other targets, you must explicitly list them in your Cargo.toml under [package.metadata.docs.rs]. This change only affects new uploads and rebuilds; previously published documentation remains untouched.

Why is docs.rs reducing the number of default build targets?

The primary motivation is efficiency. The vast majority of Rust crates do not compile different code for different targets—they are platform-independent. Building documentation for five targets when only one is needed wastes compute time and server resources. By defaulting to a single target, docs.rs reduces build times for most crate releases, lowers its infrastructure costs, and speeds up the documentation delivery pipeline. This change follows a 2020 update that allowed crate authors to opt into fewer targets; now it becomes the default. It’s a better fit for the typical crate, and if your crate truly needs multi-target documentation, you can easily opt out by defining the targets list.

Which releases are affected by this change? Will existing documentation be rebuilt?

Only new releases published after May 1, 2026, and rebuilds of old releases triggered after that date will be affected. Existing documentation that was already built before the change remains exactly as it was. This means if you have a crate with multiple versions that were previously built with five targets, those older versions will continue to display all five target docs. However, if you trigger a rebuild of an old version (e.g., through the docs.rs interface), it will then use the new single-target default unless you have explicitly set the targets list.

How does docs.rs choose the default target if I don’t set one?

If your crate does not specify a default-target in the docs.rs metadata, docs.rs automatically uses the target of its own build servers: x86_64-unknown-linux-gnu. This is a Linux x86-64 platform and serves as the fallback. You can override this by adding a default-target field under [package.metadata.docs.rs] in your Cargo.toml. For example, to use macOS as the default target, you would write default-target = "x86_64-apple-darwin". Note that this only sets the default target; if you also list additional targets, they must be listed explicitly in the targets array.

How can I build documentation for multiple targets on docs.rs?

To have docs.rs build documentation for more than the default single target, you need to specify the full list of desired targets in your Cargo.toml under [package.metadata.docs.rs]. 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 you set the targets array, docs.rs will build documentation only for those exact targets. You can list any target that the Rust toolchain supports. This opt-in mechanism preserves flexibility for crates that genuinely need cross-platform documentation, while the new default keeps the common case lightweight.

Does this change affect the ability to build documentation for any Rust target?

No, the full set of targets available in the Rust toolchain remains supported. Docs.rs can still build documentation for any target you specify in the targets list. Only the default behavior is changing—previously it built five targets by default, now it builds one. If your crate requires documentation for exotic or rare targets, you can simply include them in the list. This means the change has zero impact on the range of possible documentation, only on what happens when you don’t specify anything.

What should I do to prepare my crate for this change?

First, check whether your crate actually needs documentation for multiple targets. If it compiles the same code on all platforms (which is true for most crates), you likely do not need to change anything—the single default target will suffice. If your crate does use conditional compilation based on target (e.g., platform-specific features), you should define the targets list in your Cargo.toml before May 1, 2026. You can also set a default-target if you want documentation on a specific non-Linux platform by default. Review the docs.rs metadata documentation for exact syntax. The key is to test by building locally with the --target flag to ensure your documentation covers all needed platforms.