Guide: Configuring Target Architectures for docs.rs Documentation Builds

By ✦ min read

<h2>Overview</h2> <p>Starting <strong>May 1, 2026</strong>, docs.rs will change its default behavior for building documentation. Previously, when a crate did not specify a <code>targets</code> list in its <code>[package.metadata.docs.rs]</code> section, docs.rs would build documentation for a default set of <strong>five targets</strong>. After this date, only the <strong>default target</strong> will be built unless you explicitly request additional targets. This shift is the next step in a change first introduced in 2020, when docs.rs added support for opting into fewer build targets. Since most crates compile identical code across architectures, building fewer targets by default reduces build times and conserves resources on docs.rs. This guide explains how the new behavior works, how to control target selection, and how to avoid common pitfalls.</p><figure style="margin:20px 0"><img src="https://www.rust-lang.org/static/images/rust-social-wide.jpg" alt="Guide: Configuring Target Architectures for docs.rs Documentation Builds" 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>Prerequisites</h2> <p>Before you begin, ensure you have:</p> <ul> <li>A Rust crate with a <code>Cargo.toml</code> file.</li> <li>Basic familiarity with editing <code>Cargo.toml</code> and publishing crates.</li> <li>Access to a docs.rs account (anyone who publishes a crate to crates.io automatically gets docs.rs builds).</li> <li>Understanding of <a href="#target-triples">target triples</a> (e.g., <code>x86_64-unknown-linux-gnu</code>).</li> </ul> <h2>Step-by-Step Instructions</h2> <h3 id="understanding-the-change">1. Understanding the Change</h3> <p>As of May 1, 2026, docs.rs will only build documentation for the <strong>default target</strong> (currently <code>x86_64-unknown-linux-gnu</code>) unless you provide an explicit <code>targets</code> list. This change affects:</p> <ul> <li>New releases of crates published to crates.io.</li> <li>Rebuilds of <em>existing</em> releases requested after the cutover date.</li> </ul> <p>If your crate uses conditional compilation (<code>#[cfg(target_os = "windows")]</code>, etc.), you may need to adjust your configuration so that documentation is built for all relevant targets. Otherwise, visitors will only see docs for the default environment.</p> <h3 id="default-target-selection">2. Default Target Selection</h3> <p>If you do not set <code>default-target</code> in your <code>[package.metadata.docs.rs]</code> section, docs.rs will use the architecture of its build servers: <code>x86_64-unknown-linux-gnu</code>. To override this default, add the following to your <code>Cargo.toml</code>:</p> <pre><code>[package.metadata.docs.rs] default-target = "x86_64-apple-darwin"</code></pre> <p>This sets the default target to macOS x86_64. Any target supported by the Rust toolchain can be used here.</p> <h3 id="customizing-additional-targets">3. Customizing Additional Targets</h3> <p>To build documentation for more than one target, you must specify the complete list in the <code>targets</code> array. When this array is present, docs.rs ignores the default list and builds only for the targets you provide. 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>With this configuration, documentation will be built for <strong>exactly these five targets</strong>. If you want to keep the previous default five, include them all. If you only need two or three, list only those. Remember: docs.rs supports any Rust target triple – you are not limited to the old default set.</p> <p><strong>Important:</strong> Setting <code>targets</code> overrides the <code>default-target</code> setting. The first target in your list will be shown by default on the docs.rs page, but users can switch to others via a dropdown. To control which target is shown first, either reorder your list or continue using <code>default-target</code> (which will be ignored if <code>targets</code> is present – as of this writing, the order in <code>targets</code> determines the primary target).</p> <h3 id="verifying-your-configuration">4. Verifying Your Configuration</h3> <p>Before publishing a new release, test your configuration locally. You can simulate the docs.rs build environment using the <code>cargo doc</code> command with the <code>--target</code> flag. For a crate targeting multiple architectures, you might run:</p> <pre><code>cargo doc --target x86_64-unknown-linux-gnu cargo doc --target x86_64-apple-darwin</code></pre> <p>These commands will build documentation for each target. Verify that conditional compilation paths are correct and that docs are generated as expected. Note that docs.rs uses its own build process, but local testing catches most issues.</p> <p>After publishing, check your crate’s docs.rs page. You should see a target dropdown at the top of the documentation. If you did not specify <code>targets</code>, you will see only the default target (either the one you set or <code>x86_64-unknown-linux-gnu</code>). If you specified <code>targets</code>, all listed targets should appear.</p> <h2>Common Mistakes</h2> <ul> <li><strong>Forgetting to update the <code>targets</code> list before May 1, 2026</strong> – If your crate relies on multi-target documentation and you do not add the list, only the default target will be built after the cutover. Plan to make changes before that date.</li> <li><strong>Omitting the default target from the <code>targets</code> list</strong> – If you specify a custom list but forget to include <code>x86_64-unknown-linux-gnu</code> (or your preferred default), that target will not be built. Always double-check that you’ve included all needed architectures.</li> <li><strong>Using both <code>default-target</code> and <code>targets</code> incorrectly</strong> – Setting <code>default-target</code> alone does <em>not</em> add extra targets; it only changes the default among the built set. If you need multiple targets, you must use the <code>targets</code> array.</li> <li><strong>Assuming the old default set persists</strong> – Starting May 1, 2026, the previous default of five targets is gone. If you do nothing, you get one target. Do not rely on the old behavior.</li> <li><strong>Not testing locally</strong> – Changes to <code>targets</code> can break conditional compilation if you forget to include a target used in <code>#[cfg()]</code> directives. Always run <code>cargo doc --target &lt;triple&gt;</code> before publishing.</li> </ul> <h2>Summary</h2> <p>In summary, the docs.rs platform is streamlining its default build targets to improve efficiency. After May 1, 2026, documentation will be built for only one target (<code>x86_64-unknown-linux-gnu</code> unless you override <code>default-target</code>) unless you explicitly specify a <code>targets</code> list in <code>Cargo.toml</code>. This change does not limit the available targets – you can still choose any Rust target triple. To ensure your crate’s documentation is available for all the architectures your users need, update your <code>package.metadata.docs.rs</code> section accordingly. Use the steps above to configure your defaults, add a <code>targets</code> array, and verify your build. By planning ahead, you can avoid surprises and keep your documentation accessible to everyone.</p>