Guide: Configuring Target Architectures for docs.rs Documentation Builds

Overview

Starting May 1, 2026, docs.rs will change its default behavior for building documentation. Previously, when a crate did not specify a targets list in its [package.metadata.docs.rs] section, docs.rs would build documentation for a default set of five targets. After this date, only the default target will be built unless you explicitly request additional targets. This shift is the next step in a change first introduced in 2020, when docs.rs added support for opting into fewer build targets. Since most crates compile identical code across architectures, building fewer targets by default reduces build times and conserves resources on docs.rs. This guide explains how the new behavior works, how to control target selection, and how to avoid common pitfalls.

Prerequisites

Before you begin, ensure you have:

• A Rust crate with a Cargo.toml file.
• Basic familiarity with editing Cargo.toml and publishing crates.
• Access to a docs.rs account (anyone who publishes a crate to crates.io automatically gets docs.rs builds).
• Understanding of target triples (e.g., x86_64-unknown-linux-gnu).

Step-by-Step Instructions

1. Understanding the Change

As of May 1, 2026, docs.rs will only build documentation for the default target (currently x86_64-unknown-linux-gnu) unless you provide an explicit targets list. This change affects:

• New releases of crates published to crates.io.
• Rebuilds of existing releases requested after the cutover date.

If your crate uses conditional compilation (#[cfg(target_os = "windows")], etc.), you may need to adjust your configuration so that documentation is built for all relevant targets. Otherwise, visitors will only see docs for the default environment.

2. Default Target Selection

If you do not set default-target in your [package.metadata.docs.rs] section, docs.rs will use the architecture of its build servers: x86_64-unknown-linux-gnu. To override this default, add the following to your Cargo.toml:

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

This sets the default target to macOS x86_64. Any target supported by the Rust toolchain can be used here.

3. Customizing Additional Targets

To build documentation for more than one target, you must specify the complete list in the targets array. When this array is present, docs.rs ignores the default list and builds only for the targets you provide. 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"
]

With this configuration, documentation will be built for exactly these five targets. If you want to keep the previous default five, include them all. If you only need two or three, list only those. Remember: docs.rs supports any Rust target triple – you are not limited to the old default set.

Important: Setting targets overrides the default-target setting. The first target in your list will be shown by default on the docs.rs page, but users can switch to others via a dropdown. To control which target is shown first, either reorder your list or continue using default-target (which will be ignored if targets is present – as of this writing, the order in targets determines the primary target).

4. Verifying Your Configuration

Before publishing a new release, test your configuration locally. You can simulate the docs.rs build environment using the cargo doc command with the --target flag. For a crate targeting multiple architectures, you might run:

cargo doc --target x86_64-unknown-linux-gnu
cargo doc --target x86_64-apple-darwin

These commands will build documentation for each target. Verify that conditional compilation paths are correct and that docs are generated as expected. Note that docs.rs uses its own build process, but local testing catches most issues.

After publishing, check your crate’s docs.rs page. You should see a target dropdown at the top of the documentation. If you did not specify targets, you will see only the default target (either the one you set or x86_64-unknown-linux-gnu). If you specified targets, all listed targets should appear.

Common Mistakes

• Forgetting to update the targets list before May 1, 2026 – If your crate relies on multi-target documentation and you do not add the list, only the default target will be built after the cutover. Plan to make changes before that date.
• Omitting the default target from the targets list – If you specify a custom list but forget to include x86_64-unknown-linux-gnu (or your preferred default), that target will not be built. Always double-check that you’ve included all needed architectures.
• Using both default-target and targets incorrectly – Setting default-target alone does not add extra targets; it only changes the default among the built set. If you need multiple targets, you must use the targets array.
• Assuming the old default set persists – Starting May 1, 2026, the previous default of five targets is gone. If you do nothing, you get one target. Do not rely on the old behavior.
• Not testing locally – Changes to targets can break conditional compilation if you forget to include a target used in #[cfg()] directives. Always run cargo doc --target <triple> before publishing.

Summary

In summary, the docs.rs platform is streamlining its default build targets to improve efficiency. After May 1, 2026, documentation will be built for only one target (x86_64-unknown-linux-gnu unless you override default-target) unless you explicitly specify a targets list in Cargo.toml. This change does not limit the available targets – you can still choose any Rust target triple. To ensure your crate’s documentation is available for all the architectures your users need, update your package.metadata.docs.rs section accordingly. Use the steps above to configure your defaults, add a targets array, and verify your build. By planning ahead, you can avoid surprises and keep your documentation accessible to everyone.