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

As of May 1, 2026, docs.rs will streamline its build process by defaulting to a single target instead of five. This change, building on a 2020 opt-in feature, aims to reduce unnecessary multi-target builds for crates that don't vary code between platforms. Most crates benefit from faster builds and lower resource usage. However, if your crate requires documentation for multiple targets, you'll need to explicitly configure them. Below, we answer common questions about this update.

What is changing with docs.rs build behavior in 2026?

Starting May 1, 2026, docs.rs will alter its default build behavior for new releases and rebuilds of old releases. Previously, if a crate didn't specify a targets list in its Cargo.toml metadata, docs.rs built documentation for a default set of five targets: x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, i686-unknown-linux-gnu, and i686-pc-windows-msvc. After the change, only one target will be built by default—the target of the docs.rs build servers, x86_64-unknown-linux-gnu, unless you override it. To get documentation for additional targets, you must now explicitly list them in your Cargo.toml under the [package.metadata.docs.rs] section. This change only applies to new releases and rebuilds; existing documentation remains unaffected.

Why is docs.rs making this change?

The decision to reduce default build targets stems from the observation that most Rust crates do not compile different code for different platforms. Building documentation for five targets when only one is necessary wastes build time and server resources. Docs.rs first introduced support for opting into fewer targets back in 2020, and the data shows that the vast majority of crates are platform-independent. By defaulting to a single target, docs.rs can allocate its resources more efficiently, resulting in faster documentation generation for most releases. This change aligns with the principle of sensible defaults—providing what most users need while allowing those with specific requirements to opt into more. It also reduces the carbon footprint of the documentation service, making it more sustainable in the long run.

How is the default target chosen?

If you do not set a default-target in your docs.rs metadata, the system will use the target of its build servers: x86_64-unknown-linux-gnu. You can override this by adding the default-target key to your Cargo.toml under [package.metadata.docs.rs]. For example, to build documentation for x86_64-apple-darwin by default, include default-target = "x86_64-apple-darwin". Note that this setting only affects the primary target; if you need documentation for multiple platforms, you must also specify the targets list. The default-target field is optional, and omitting it means the build server's native target is used. This flexibility ensures that crates targeting niche platforms can still have relevant documentation without unnecessary builds.

How do I build documentation for additional targets?

If your crate requires documentation for more than the default target, you must define the full list explicitly in your Cargo.toml under [package.metadata.docs.rs]. Set the targets array with the desired triples, 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 targets is set, docs.rs will build documentation for exactly those targets, ignoring the default. The targets list can include any target available in the Rust toolchain—it doesn't have to be limited to the previous default set. Keep in mind that the default-target setting is ignored if targets is present. This explicit approach gives you full control over which platform docs are generated, which is essential for crates that contain platform-specific code (e.g., OS-specific system calls or CPU intrinsics).

Will existing releases be affected?

No, the change only applies to new releases and rebuilds of old releases that occur after May 1, 2026. Documentation that has already been built and published on docs.rs will remain unchanged. If you have an old release that you trigger a rebuild for (e.g., due to a documentation fix or dependency update), that rebuild will follow the new default behavior unless you have since modified the crate's metadata. This means you may see fewer targets for the rebuilt version compared to the original if you haven't set explicit targets. To avoid any surprises, it's a good idea to review and update your Cargo.toml metadata before requesting a rebuild. The change is intentional to encourage maintainers to be explicit about their documentation needs.

Can I still build for any target I want?

Absolutely. Docs.rs continues to support any target available in the Rust toolchain, including niche ones like aarch64-linux-android or wasm32-unknown-unknown. What has changed is only the default behavior—if you don't specify a targets list, you get just the default target. If you need documentation for a different set of targets, simply list them in your Cargo.toml as described above. The underlying infrastructure remains the same; docs.rs can still build for all the same platforms. This change simply removes the blanket five-target default, which was wasteful for most crates. So yes, you can still build for any target—you just need to tell docs.rs explicitly which ones you want.