docs.rs: building fewer targets by default
Building fewer targets by default On 2026-05-01 , docs.rs will make a breaking change to its build behavior. Today, if a crate does not define a targets list in its docs.rs metadata , docs.rs builds documentation for a default list of five targets. Starting on 2026-05-01 , docs.rs will instead build documentation for only the default target unless additional targets are requested explicitly. This is the next step in a change we first introduced in 2020, when docs.rs added support for opting into fewer build targets. Most crates do not compile different code for different targets, so building fewer targets by default is a better fit for most releases. It also reduces build times and saves resources on docs.rs. This change only affects: new releases rebuilds of old releases How is the default target chosen? If you do not set default-target , docs.rs uses the target of its build servers: x86_64-unknown-linux-gnu . You can override that by setting default-target in your docs.rs metadata : [ package . metadata . docs . rs ] default-target = " x86_64-apple-darwin " How do I build documentation for additional targets? If your crate needs documentation to be built for more than the default target, define the full list explicitly in your Cargo.toml : [ 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
On May 1, 2026, docs.rs, the primary source for Rust documentation, will implement a significant change in its build behavior. Currently, if a Rust crate does not specify a targets list in its docs.rs metadata, the platform builds documentation for a default list of five targets. Starting from May 1, 2026, docs.rs will only build documentation for the default target unless additional targets are explicitly requested. This change represents an evolution from a similar modification introduced in 2020, when docs.rs began offering the option to opt into fewer build targets.
The rationale behind this shift is rooted in the fact that most Rust crates do not require different code compilation for various targets. By defaulting to a single target, docs.rs aims to better align with the needs of the majority of crate releases. Additionally, this change reduces build times and conserves computational resources on the docs.rs servers. Importantly, this update will only impact new releases and rebuilds of older releases, ensuring that existing documentation remains unaffected unless the crate maintainers choose to update their metadata.
The default target is determined by the build servers' target configuration, which is currently set to x86_64-unknown-linux-gnu. However, crate maintainers have the flexibility to override this default by specifying a custom target in their Cargo.toml file under the docs.rs metadata section. For instance, they can set the default-target as follows:
```toml
[package.metadata.docs.rs]
default-target = "x86_64-apple-darwin"
```
For crates that require documentation to be built for more than one target, maintainers can explicitly define the list of targets in their Cargo.toml file. This ensures that docs.rs builds documentation for the specified targets. Here's an example of how to define multiple targets:
```toml
[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 the targets list is provided, docs.rs will build documentation exclusively for those targets. It's essential to note that while the default behavior is changing, docs.rs continues to support any target available in the Rust toolchain. The modification pertains solely to the default settings, allowing maintainers to customize the build process as needed.
This change underscores docs.rs's commitment to optimizing resource usage and aligning with the needs of the Rust community. By reducing the number of targets built by default, the platform not only enhances efficiency but also encourages maintainers to focus on the most relevant documentation, ultimately benefiting users seeking accurate and up-to-date information about Rust crates.
