Understanding docs.rs Default Build Targets: A Migration Guide

Overview

Starting 2026-05-01, docs.rs will change its default build behavior: instead of building documentation for five default targets, it will build only for a single target (the default target). This tutorial explains why this change is happening, how it affects your crate, and what you need to do to continue building documentation for multiple targets if required.

Understanding docs.rs Default Build Targets: A Migration Guide — Source: blog.rust-lang.org

The change is the culmination of a gradual process that began in 2020 when docs.rs first allowed opting into fewer build targets. Most crates compile identically across platforms, so building for only one target saves time and server resources. This update affects new releases and rebuilds of old releases submitted after the cutoff date.

Prerequisites

A Rust crate published to crates.io
Familiarity with Cargo.toml syntax and the [package.metadata] section
Knowledge of Rust target triples (e.g., x86_64-unknown-linux-gnu)
Optional: access to your crate’s docs.rs build settings (if you have administrator rights)

Step-by-Step Instructions

1. Determine if Your Crate Needs Multiple Targets

Before making any changes, assess whether your crate contains platform-specific code (cfg(target_os = ...), cfg(target_arch = ...), etc.) or uses conditional compilation that differs between targets. If your crate is platform-agnostic (no #[cfg] attributes regarding OS or architecture), you likely do not need multiple targets.

Common scenarios that do require multiple targets:

Using std::os::unix vs std::os::windows
Inline assembly or FFI that varies per platform
Crates that expose platform-specific features (e.g., raw file descriptors)

2. Understand How the Default Target Is Chosen

If your Cargo.toml does not specify a default-target in [package.metadata.docs.rs], docs.rs will use its own build server’s target: x86_64-unknown-linux-gnu.

To override the default target, add this to your Cargo.toml:

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

Replace the triple with your desired default. This target is the one that will be built when no explicit targets list is provided.

3. Explicitly Specify Additional Targets

If you need documentation for more than one target, you must define the full list under [package.metadata.docs.rs] using the targets key. 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 list. You can include any target triple that the Rust toolchain supports.

Note: If you set targets, you do not need to also set default-target; the first entry in your list effectively becomes the default.

4. Prepare for the Change Deadline

The new behavior takes effect on 2026-05-01. To ensure your future releases and rebuilds are not affected, update your Cargo.toml before that date. After the change, if you neither set targets nor default-target, only the build server’s default (x86_64-unknown-linux-gnu) will be built.

Common Mistakes

Assuming the old five-target default will persist. It will not after 2026-05-01. Explicitly list targets if you need more than one.
Omitting the default target from the list. If you define targets, include the target you want as the primary build (often x86_64-unknown-linux-gnu).
Confusing default-target with targets. default-target only sets which single target is built when no targets list is provided. It does not add extra targets.
Not testing after making changes. After updating Cargo.toml, trigger a rebuild on docs.rs (e.g., by pushing a new patch of your crate) to verify the correct number of documentation builds appear.

Summary

The default build target behavior on docs.rs changes on 2026-05-01: only one target will be built unless you explicitly list additional targets in [package.metadata.docs.rs]. Most crates do not require multiple targets, so this change reduces build time and resource usage. If your crate does need multi-target documentation, set the targets array with the required triples. Review your crate’s conditional compilation usage, and update Cargo.toml before the deadline to avoid disruption.

Tags: