Mastering docs.rs Build Targets: A Step-by-Step Guide to the New Defaults

Introduction

Starting on 2026-05-01, docs.rs will change how it builds documentation for crates that don't explicitly list targets. Previously, if your Cargo.toml lacked a targets array, docs.rs would build docs for five default targets. After the change, only the default target (usually x86_64-unknown-linux-gnu) will be built unless you specify otherwise. This shift, first announced in 2020, reduces build times and saves resources—most crates don’t vary code between targets. This guide walks you through everything you need to know, from understanding the change to updating your configuration. Use the specifying targets step if you need multiple targets.

What You Need

• Basic familiarity with Cargo.toml and [package.metadata.docs.rs].
• Access to your crate’s repository (to edit Cargo.toml).
• Knowledge of which Rust targets your crate actually supports.
• Optional: a local Rust toolchain to test builds.

Step 1: Understand the Change

Before updating anything, grasp what’s happening. Currently, if your Cargo.toml has no targets list under [package.metadata.docs.rs], docs.rs builds for five platforms: x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, i686-unknown-linux-gnu, and i686-pc-windows-msvc. After 2026-05-01, only the default target (x86_64-unknown-linux-gnu unless you change it) will be built. This only affects new releases and rebuilds of old releases. Existing documentation remains untouched.

Step 2: Determine Your Default Target

Your crate’s default target is where most of its users likely run it. By default, docs.rs uses its own build server’s target: x86_64-unknown-linux-gnu. You can override this by setting default-target in your docs.rs metadata:

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

Choose a target that matches your primary audience. If you’re unsure, keep the default Linux target—it’s the most common.

Step 3: Specify Additional Targets

If your crate has conditional compilation or platform-specific code, you may need documentation for more than one target. To do so, define the full list explicitly in your Cargo.toml:

[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 builds documentation for exactly those targets. You can include any target supported by the Rust toolchain. This list overrides the default behavior entirely.

Step 4: Use default-target as a Simpler Alternative

If you only need to change the single default target (e.g., because your users are macOS-heavy), simply set default-target without specifying targets. This keeps the “one target” build but changes which one. For example:

[package.metadata.docs.rs]
default-target = "x86_64-pc-windows-msvc"

That will build docs for Windows only. This is the lightest option and saves the most resources.

Step 5: Test Your Configuration

Before a new release, simulate the behavior. You can run cargo doc --target <target> locally to verify your crate compiles on each target you plan to include. Also, check that any #[cfg(...)] directives are covered appropriately. For rebuilds, note that after 2026-05-01, re-triggering a build will use the new defaults unless you’ve updated your metadata.

Step 6: Plan for Future Releases

If you do nothing, your next release after 2026-05-01 will only produce docs for the default target. That might be fine if your crate is truly platform-agnostic. However, if you rely on multiple targets for visibility (e.g., on crates.io’s documentation page), act now. Set either targets or default-target before your next publish.

Tips

• Don’t copy the old five-target list blindly – Only include targets your crate actually uses. Most crates don’t need all five.
• Use docs.rs metadata syntax correctly – Remember the double quotes around target names and the comma after each (except the last).
• Check the platform support table for target triple spelling.
• Consider contributing to docs.rs infrastructure – Fewer builds mean faster queue times for everyone.
• Test after updating – Run cargo doc locally with your chosen targets to catch compile errors early.
• Remember the effective date – 2026-05-01. Mark your calendar if you have crates that need updates.