How to Prepare Your Crate for docs.rs‘s New Default Target Behavior

Introduction

Starting 2026-05-01, docs.rs will change its default build behavior. Currently, if your crate’s Cargo.toml does not specify a targets list in the [package.metadata.docs.rs] section, docs.rs builds documentation for five default targets. After that date, it will build only for the default target unless you explicitly ask for more.

This change is the next step in an opt-in system first introduced in 2020. The reasoning is simple: most crates compile identically across targets, so building fewer targets by default saves build time and server resources. It also makes your documentation updates faster.

Who is affected? This change affects:

• New releases of any crate
• Rebuilds of old releases

If you already have a targets list set, nothing changes for you. If you rely on the defaults, read on.

What You Need

• A Rust crate with a Cargo.toml file
• Understanding of your crate’s platform-specific code (if any)
• Knowledge of which targets are relevant for your users
• Access to docs.rs (to verify builds after changes)

Step-by-Step Guide

Step 1: Understand the Default Target

If you do not set default-target in your docs.rs metadata, the default target is x86_64-unknown-linux-gnu (the same as the build server). This is a sensible default for most crates because Linux is the most common platform for documentation consumption.

However, you can change it to any target supported by the Rust toolchain. For example, if your crate is primarily used on macOS, you might override it.

Step 2: Check Your Current Configuration

Open your Cargo.toml and look for a [package.metadata.docs.rs] section. If it exists, check whether you have a targets key. If you do, you are already opted in and can skip the rest. If not, you are currently relying on the old default five targets.

If the section is missing entirely, you are also relying on the defaults.

Step 3: Decide If You Need Multiple Targets

Ask yourself: does your crate compile different code on different platforms? Common reasons include:

• Using conditional compilation with cfg attributes (e.g., #[cfg(target_os = "windows")])
• Providing platform-specific APIs or re-exports
• Having dependencies that vary by target

If your crate is entirely cross-platform without conditional compilation, building for one target is likely sufficient. If you do have platform-specific code, you probably want documentation for multiple targets so that users on each platform can see the correct API.

Step 4: Set a Default Target (Optional)

If you only need documentation for one target, you can either stick with the default (Linux) or override it. To override, add this to your Cargo.toml:

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

Replace the target triple with the one you prefer. This is useful if your primary audience uses a specific platform.

Step 5: Define an Explicit Targets List

If you need documentation for more than one target, provide the full list 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 will build documentation for exactly those targets – no more, no less. You can use any target from the Rust toolchain.

Step 6: Test Your Configuration (Optional)

While you can’t directly trigger a docs.rs build on demand, you can:

• Run cargo doc locally for each target you intend to support (using --target) and verify that the documentation renders correctly.
• Push a new release to crates.io after making changes, then check the resulting docs.rs page.

Step 7: Prepare for the Deadline

The change takes effect on 2026-05-01. Before that date:

• If you want to keep the current behavior (five targets), add an explicit targets list as shown in Step 5.
• If you are happy with only one target, you can do nothing (but consider setting default-target if the default Linux target isn’t ideal).
• For crates that need multiple targets but have no targets list, you must add one to avoid losing documentation for those platforms.

Tips

• Keep it simple: If your crate has no conditional compilation, stick with the default target. It reduces build time and resource usage.
• Use a smaller targets list: Instead of the old five, consider just two or three major platforms (Linux, macOS, Windows). Many crates don’t need i686 anymore.
• Check your dependencies: Sometimes platform-specific behavior comes from dependencies. Review their docs too.
• Monitor after the change: After May 1, 2026, check your docs.rs page after a release to ensure it builds as expected.
• Document your choice: Add a comment in your Cargo.toml explaining why you chose certain targets – helpful for collaborators.

By following these steps, you can seamlessly adapt to docs.rs’s new default behavior and ensure your crate’s documentation remains accessible to your users on all platforms they need.