Upcoming Changes to docs.rs Default Build Targets

Starting May 1, 2026, docs.rs will update its default build behavior to reduce the number of targets built automatically. This adjustment aims to save resources and streamline the documentation process for most crates. The following Q&A covers key details about the change, how it affects your projects, and steps to customize target configurations.

What specific change is happening to docs.rs default builds?

Currently, when a crate doesn’t specify a targets list in its docs.rs metadata, documentation is built for five default targets. After May 1, 2026, docs.rs will build documentation for only the default target unless additional targets are explicitly requested. This is a continuation of a shift first introduced in 2020, which allowed crates to opt into fewer build targets. The new default better aligns with the reality that most crates do not compile different code across platforms.

Upcoming Changes to docs.rs Default Build Targets — Source: blog.rust-lang.org

When will the new default take effect?

The change goes live on May 1, 2026. It applies only to new releases and rebuilds of old releases triggered after that date. Existing documentation already built before the cutoff remains unchanged.

Why is docs.rs making this change?

Building documentation for multiple targets consumes significant time and server resources. Since the vast majority of crates are platform-agnostic (their code compiles identically on all targets), generating docs for five targets offers little value. By defaulting to a single target, docs.rs reduces build queues, speeds up documentation updates, and lowers operational costs—all without compromising functionality for crates that genuinely need multi-target docs.

How is the default target selected?

If you do not set a default-target in your Cargo.toml metadata, docs.rs will use its build server’s target: x86_64-unknown-linux-gnu. You can override this by adding a default-target field under [package.metadata.docs.rs] in your Cargo.toml. For example:

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

This ensures your documentation is built specifically for the platform you care about most.

How do I build documentation for more than the default target?

If your crate requires documentation for multiple targets, explicitly list them using the targets key in [package.metadata.docs.rs] within your Cargo.toml. 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. Remember, only the default behavior is changing—docs.rs still supports any target available in the Rust toolchain.

Will this change affect documentation already published on docs.rs?

No, the change only applies to new releases and rebuilds of old releases initiated after May 1, 2026. Documentation that was built before this date will remain available with its original target configuration. To update a previously published crate, you would need to trigger a rebuild—and that rebuild would then use the new single-target default unless you override it.

Tags: