Optimizing docs.rs Builds: A Guide to Reducing Default Targets

Overview

Starting May 1, 2026, docs.rs will change its default build behavior to build documentation for only one target — the default build server target (x86_64-unknown-linux-gnu) — unless you explicitly request additional targets. This is a breaking change that affects new releases and rebuilds of old releases after that date.

Optimizing docs.rs Builds: A Guide to Reducing Default Targets — Source: blog.rust-lang.org

Currently, when a crate doesn't define a targets list in its docs.rs metadata, the platform builds documentation for a default set of five targets. The new default reduces that to just one, saving compute resources and speeding up build times. This change continues a direction first set in 2020, when docs.rs added support for opting into fewer targets. Most crates don't compile platform‑specific code, so building fewer targets by default is a better fit for the majority of releases.

Prerequisites

Before adjusting your crate's docs.rs configuration, you should be familiar with:

The basic structure of a Cargo.toml file.
The concept of docs.rs build metadata under [package.metadata.docs.rs].
Target triples (e.g., x86_64-unknown-linux-gnu) and how they relate to Rust compilation.

No prior changes to your docs.rs configuration are required; this guide works for any crate, regardless of current settings.

Step‑by‑Step Instructions

1. Understanding How the Default Target Is Chosen

If you do not set default-target in your [package.metadata.docs.rs] section, docs.rs uses the build server's platform: x86_64-unknown-linux-gnu. You can override this default by specifying a different target triple.

2. Setting a Custom Default Target

To change the default target (the one that will be built even when no targets list is provided), add this to your Cargo.toml:

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

Replace x86_64-apple-darwin with any valid Rust target triple. This setting only affects the default target; additional targets must be listed separately.

3. Building Documentation for Additional Targets

If your crate needs documentation built for more than one target, you must define the explicit list of all desired targets using the targets key. When targets is set, docs.rs builds documentation for exactly those targets — it no longer uses the default list.

Example configuration for building five targets (the old default list):

[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"
]

You can include any target that the Rust toolchain supports — docs.rs still supports all of them. Only the default list (when targets is absent) is changing.

4. Combining `default-target` and `targets`

If you set both default-target and targets, note that default-target does not affect the list built when targets is present. The targets array completely replaces the default list. However, default-target is still used as the primary target for cross‑reference links and other docs.rs features. It's a good practice to include the default-target in your targets list to ensure consistency.

5. Example: A Complete Configuration

Suppose you maintain a crate that is used on both Linux and macOS, but not on Windows or 32‑bit architectures. You want the documentation to reflect your primary development platform (macOS) but also include Linux. Here's a sample Cargo.toml:

[package]
name = "my-crate"
version = "1.0.0"

[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"
targets = [
    "x86_64-apple-darwin",
    "x86_64-unknown-linux-gnu"
]

After the change on May 1, 2026, this configuration will build documentation for exactly those two targets — and nothing else. Without defining targets, it would have built only for x86_64-apple-darwin (or the server default if default-target were omitted).

Common Mistakes

Forgetting to add [package.metadata.docs.rs] section: The metadata section must be exactly as shown. Typos like [package.metadata.docs.rs] vs [package.metadata.docs_rs] will be ignored.
Setting default-target but not targets: If you change the default target but don't provide a targets list, only that single target (the new default) will be built after May 1, 2026. If you need more, include the targets list.
Assuming default-target adds targets to the default list: default-target only changes which single target is built when targets is absent. It does not add targets to any existing list.
Omitting the default target from targets: If you set default-target to one triple but your targets list doesn't include it, default-target may still be used as the primary target for some features, leading to confusion. Always include your default-target in the targets list if you want it built.
Not testing the configuration: After updating your Cargo.toml, you can simulate the new behavior locally by triggering a build with the --target flag for each desired target. However, note that docs.rs respects the metadata section only when building on its infrastructure.

Summary

Starting May 1, 2026, docs.rs will build documentation for only the default target (or your custom default-target) if no targets list is provided. To keep the previous behavior of building documentation for multiple targets, you must explicitly list them in your Cargo.toml under [package.metadata.docs.rs] targets = [...]. This change reduces resource usage and build times while encouraging crate authors to specify only the targets that matter for their project. Update your configuration before the cutoff date to avoid missing documentation for alternative platforms.