How to Adjust Your Crate's Docs.rs Build Targets After the 2026 Default Change

By • min read

Introduction

Starting on May 1, 2026, docs.rs will simplify its default documentation builds. Instead of building documentation for five default targets, it will now build documentation only for the default target (typically x86_64-unknown-linux-gnu) unless you explicitly specify additional targets. This change is a continuation of the opt-in feature introduced in 2020, and it aims to reduce build times and conserve resources—since most crates compile the same code across all targets. This guide walks you through updating your Cargo.toml to maintain or customize your crate's documentation builds.

How to Adjust Your Crate's Docs.rs Build Targets After the 2026 Default Change — Source: blog.rust-lang.org

What You Need

A Cargo.toml file for your Rust crate.
Basic familiarity with conditional compilation (optional but helpful).
The ability to publish crate updates (for the changes to take effect on docs.rs).
An understanding of which targets your crate supports (if any).

Step-by-Step Instructions

Step 1: Understand the Scope of the Change

Before making any modifications, recognize that the change applies only to new releases and rebuilt old releases. If your crate currently has no [package.metadata.docs.rs] targets list, it will automatically build for just the default target (the server’s target, usually x86_64-unknown-linux-gnu). If you rely on documentation for multiple platforms (e.g., macOS, Windows), you need to act now.

Step 2: Determine Your Crate’s Target Needs

Ask yourself: Does my crate use conditional compilation or platform-specific code? If your crate uses #[cfg(target_os)], #[cfg(not(target_…))], or similar attributes, you likely need documentation for each target that has distinct code paths. If all code is generic, a single target build is sufficient.

Step 3: Check Your Current Docs.rs Metadata

Open your Cargo.toml and look for a [package.metadata.docs.rs] section. It might already contain a targets or default-target setting. If it does, your build behavior is already customized. If not, you are affected by the new default.

Step 4: Override the Default Target (Optional)

If you want documentation built for a different single target (e.g., macOS), set the default-target field:

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

This tells docs.rs to build for that target instead of the Linux server target. Use this when you only need one non-Linux target.

Step 5: Define a Custom List of Targets

If you need documentation for multiple targets, explicitly list them in the targets array:

[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 present, docs.rs will build documentation exactly for those targets, ignoring the default list. You can include any target supported by the Rust toolchain.

Step 6: Test Locally (Optional but Recommended)

Before publishing, you can simulate the docs.rs build behavior by running cargo doc --target <target> for each target you intend to include. This helps catch any platform-specific compilation errors early. Note that docs.rs uses a specific nightly toolchain, but local testing with stable is a good starting point.

Step 7: Publish Your Updated Crate

After adding or modifying the [package.metadata.docs.rs] section in Cargo.toml, publish a new version of your crate. Docs.rs will then rebuild the documentation using your new settings. Only new versions are affected; older releases remain unchanged until manually rebuilt.

Tips

Don’t mix default-target and targets – If you set targets, it overrides any default-target. Use one or the other.
Check the list of Rust targets – You can see all official targets with rustc --print target-list. Add only those your crate actually requires to keep build fast.
Remember the transition date – The new default behavior goes into effect on May 1, 2026. Update your metadata before then to avoid surprises.
Test with --all-features – If your crate uses features that affect target-specific code, run cargo doc --all-features locally to catch any broken docs.
For complex crates – Use the targets list even if you only need one non-default target. It’s more explicit and avoids future ambiguity.

Internal links: Step 2 – determine your needs · Step 5 – set targets