Docs.rs Shifts Default: Fewer Build Targets Ahead

<p>Starting May 1, 2026, docs.rs will change its default build behavior to reduce the number of targets for which documentation is automatically generated. Currently, if a crate doesn't specify a target list in its metadata, docs.rs builds docs for five default targets. After the change, only the default target (usually the build server's target) will be built unless you explicitly request more. This move, building on a change from 2020 that allowed opting into fewer targets, aims to save resources and shorten build times, as most crates don't vary code across targets. Below, we address common questions about this update.</p> <h2 id="breaking-change">What is the precise breaking change coming to docs.rs in 2026?</h2> <p>Starting on May 1, 2026, docs.rs will no longer build documentation for a default list of five targets if a crate lacks a <code>targets</code> field in its <code>[package.metadata.docs.rs]</code> section. Instead, it will build only for the <strong>default target</strong> (the host target of the docs.rs build servers, e.g., <code>x86_64-unknown-linux-gnu</code>, unless you set <code>default-target</code>). This is a breaking change because it reverts the previous multi-target default. Crates that rely on automatic cross-target builds must now explicitly list their desired targets in <code>Cargo.toml</code> or accept the single-target default.</p><figure style="margin:20px 0"><img src="https://www.rust-lang.org/static/images/rust-social-wide.jpg" alt="Docs.rs Shifts Default: Fewer Build Targets Ahead" 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> <h2 id="why-change">Why is docs.rs making this change?</h2> <p>The change reduces unnecessary builds. Most Rust crates compile identical code across different platforms—they don't use conditional compilation for each target. Building documentation for five targets when only one is needed wastes docs.rs’s compute time, increases build queues, and consumes more storage. The 2020 opt-in for fewer targets proved that the majority of crate authors prefer simpler defaults. By switching the default to a single target, docs.rs aligns its resource consumption with actual usage, making the service more efficient for everyone while still supporting multi-target builds when explicitly requested.</p> <h2 id="affected-builds">Which documentation builds are affected by this change?</h2> <p>Only <strong>new releases</strong> and <strong>rebuilds of existing releases</strong> that occur after May 1, 2026, are affected. Documentation that was already built before that date will remain unchanged. If you trigger a rebuild of a previously published crate, it will follow the new single-target default unless you update your <code>targets</code> list. The change does not retroactively alter existing documentation pages, so your older docs will keep their current target coverage until you publish a new version or force a manual rebuild.</p> <h2 id="default-target-selection">How is the default target chosen for my crate?</h2> <p>If you don't specify a <code>default-target</code> in your crate’s <code>[package.metadata.docs.rs]</code> section, docs.rs uses the target of its own build servers, which is <code>x86_64-unknown-linux-gnu</code> (the standard Linux x86-64 environment). You can override this by setting a different <code>default-target</code>, for example:</p> <pre><code>[package.metadata.docs.rs] default-target = "x86_64-apple-darwin"</code></pre> <p>This target will then be the sole one built unless you add a <code>targets</code> list. Note that the <code>default-target</code> field only controls which single target is used when no <code>targets</code> list is provided; it does not extend the list of targets built.</p> <h2 id="multiple-targets">How do I build documentation for additional targets?</h2> <p>To have docs.rs build documentation for multiple targets, you must explicitly define the full list in your <code>Cargo.toml</code> under <code>[package.metadata.docs.rs]</code> using the <code>targets</code> key. For example:</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 set, docs.rs builds documentation for <strong>exactly</strong> those targets. This list replaces the old default, so it must include all the targets you want—including the default target if you still want it. You can list any target available in the Rust toolchain; this change only affects the default behavior, not the set of supported targets.</p> <h2 id="any-target">Can I still use any target from the Rust toolchain?</h2> <p>Yes, absolutely. The change only alters the <strong>default</strong> list of targets built when no <code>targets</code> field is present. The docs.rs service continues to support every target that the Rust toolchain supports. By setting the <code>targets</code> key to an array of target triples, you can build documentation for any combination of platforms, including niche ones like <code>aarch64-unknown-linux-gnu</code> or <code>wasm32-unknown-unknown</code>. The underlying infrastructure remains unchanged—only the set of targets built automatically is reduced to one.</p> <h2 id="maintain-current">What should I do to maintain the current multi-target behavior?</h2> <p>If your crate currently relies on the default five-target builds and you want to preserve that behavior after May 2026, you need to add an explicit <code>targets</code> list to your <code>Cargo.toml</code>. Copy the five targets previously used by docs.rs into your metadata:</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>Alternatively, if you only need one specific target, you can keep the new default or set <code>default-target</code>. The recommendation is to review your crate’s conditional compilation and only build for targets where it actually differs. This saves time and resources on docs.rs while keeping documentation complete where needed.</p>