docs.rs to Slash Default Build Targets from Five to One in Major Change

By ● min read

<h2>Breaking Change Coming May 1, 2026: docs.rs Reduces Default Build Targets</h2> <p>Starting May 1, 2026, docs.rs will build documentation for only the default target by default, a dramatic reduction from the current five-target default. The change aims to cut build times and reduce server load, but requires crate maintainers to explicitly list any additional targets they need.</p><figure style="margin:20px 0"><img src="https://www.rust-lang.org/static/images/rust-social-wide.jpg" alt="docs.rs to Slash Default Build Targets from Five to One in Major Change" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: blog.rust-lang.org</figcaption></figure> <p>"This is about matching the behavior to what most crates actually need," said a docs.rs team spokesperson. "The vast majority of Rust crates do not compile different code for different platforms, so building for five targets is wasteful."</p> <h3>Background</h3> <p>The shift builds on a 2020 change that first allowed crates to opt into fewer targets. At that time, docs.rs added support for crate-level target configuration through metadata fields. The current default of five targets was set when the service launched, but usage data now shows that less than 5% of crates customize their target list.</p> <p>"We've been monitoring build volumes for years," the spokesperson added. "Most users never touch the default, and those who do often only need one or two specific platforms. This change aligns the default with reality."</p> <h3>What Is Changing?</h3> <p>When a crate does not define a <code>targets</code> list in its <code>[package.metadata.docs.rs]</code> section, docs.rs currently builds documentation for five targets: x86_64-unknown-linux-gnu, x86_64-apple-darwin, x86_64-pc-windows-msvc, i686-unknown-linux-gnu, and i686-pc-windows-msvc.</p> <p>After May 1, 2026, if no <code>targets</code> list is provided, only the default target will be built. The default target defaults to <code>x86_64-unknown-linux-gnu</code> (the build server's own architecture), but crate authors can <a href="#override-default-target">override it</a> using the <code>default-target</code> metadata field.</p> <p>The change affects only:<br> • New crate releases<br> • Rebuilds of existing releases</p> <h3 id="override-default-target">How to Override the Default Target</h3> <p>Crate maintainers can set a different default target by adding <code>default-target</code> to their Cargo.toml:</p> <pre><code>[package.metadata.docs.rs] default-target = "x86_64-apple-darwin"</code></pre> <h3>How to Build Documentation for Multiple Targets</h3> <p>If your crate requires documentation for more than one target (e.g., because of conditional compilation or platform-specific APIs), define the full target list explicitly:</p> <pre><code>[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" ]</code></pre> <p>When the <code>targets</code> list is set, docs.rs builds documentation for exactly those targets. The service still supports all Rust toolchain targets; only the default behavior is changing.</p> <h3>What This Means for Developers</h3> <p>For maintainers of crates that use conditional compilation per target (e.g., <code>#[cfg(target_os = "windows")]</code>), this change requires explicit action. Without adding a <code>targets</code> list, users visiting docs.rs will only see documentation for a single platform.</p> <p>"Most crate authors won't notice any difference," said the docs.rs team. "But if you rely on platform-specific docs, you must update your Cargo.toml before May 1 to avoid broken or incomplete documentation pages."</p> <p>The move also reduces overall build load on docs.rs servers, potentially speeding up the documentation pipeline for all crates. Smaller crates with no target-specific code will see faster rebuilds.</p> <p>To verify your crate is ready, use <code>cargo doc</code> locally with the appropriate <code>--target</code> flags. Alternatively, check your <code>[package.metadata.docs.rs]</code> configuration now and ensure any needed targets are listed.</p>