5 Key Facts About docs.rs's New Default Build Target Policy

Starting on May 1, 2026, docs.rs will implement a significant change to how it builds documentation for Rust crates. Instead of building for five default targets, it will now build only for the default target unless you explicitly request more. This adjustment aims to streamline resource usage and reduce build times. In this article, we break down the five essential things you need to know to ensure your crate's documentation remains up-to-date.

1. The Core Change: From Five Targets to One

Currently, if your Cargo.toml does not specify a targets list under [package.metadata.docs.rs], docs.rs builds documentation for five default targets: x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, i686-unknown-linux-gnu, and i686-pc-windows-msvc. After May 1, 2026, docs.rs will build documentation for only the single default target (x86_64-unknown-linux-gnu) unless you explicitly list additional targets. This change applies to new releases and rebuilds of old releases; existing documentation remains untouched.

2. Why Fewer Targets by Default?

This update is the next step in a path started in 2020, when docs.rs first allowed opting into fewer targets. The rationale is simple: most crates do not compile different code for different targets. Building documentation for multiple targets is often redundant and consumes unnecessary compute resources. By reducing the default, docs.rs cuts build times and server load, making the service more efficient for everyone. The change is a better fit for most releases and aligns with the principle of doing only what is needed unless told otherwise.

3. How Is the Default Target Determined?

If you don't set a custom default, docs.rs uses x86_64-unknown-linux-gnu—the target of its build servers. However, you can override this by adding default-target in your docs.rs metadata. For example:

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

This is useful if your crate is primarily used on macOS or another platform. Keep in mind that the default target is the one that will be built if no targets list is provided. If you later define a targets list, the default-target field is ignored in favor of that explicit list.

4. How to Request Additional Targets

If your crate does need documentation for multiple platforms—for example, because it uses conditional compilation or targets system-specific APIs—you must specify the full list explicitly. In your Cargo.toml, add:

[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—no more, no less. Note that docs.rs still supports any target available in the Rust toolchain; only the default behavior is changing.

5. What You Need to Do Next

If your crate already specifies a targets list, no action is required—your settings remain unchanged. If you rely on the default five-target build and want to keep that, add the explicit list above before May 1, 2026. If you are fine with only the default target, do nothing. To be safe, review your crate's docs.rs metadata today. For most crates, this change will be seamless, but taking a moment to verify ensures that your documentation continues to appear correctly for your users.

In conclusion, docs.rs's shift to building fewer targets by default is a resource-saving measure that reflects typical crate usage. By understanding these five points, you can easily adapt your configuration and avoid any surprises when the change takes effect on May 1, 2026.