Headstart lets Rust crates compile before dependencies finish checking, up to 54% faster

What headstart does

A project called headstart, which reached the Hacker News front page, patches the Rust compiler and Cargo so that a crate no longer sits idle while the crates it depends on finish being checked. rustc writes out interface metadata as soon as a dependency's signatures are verified, and Cargo launches dependent crates at that point, letting the dependency's function bodies be checked while downstream work is already underway.

The Hacker News item characterized the result as builds and checks getting up to twice as fast. According to the project's own measurements on a 16-core machine, the improvements top out at 54% for clean cargo check runs and 42% for cargo build across 13 real projects, with none of them getting slower.

Why the waiting was unnecessary

In a standard Rust build, every crate waits until all of its dependencies have been fully checked, function bodies included, before it can start. That ordering is stricter than the type system requires: to check a dependent crate, rustc needs only the dependency's interface, stored as metadata in its .rmeta file, not the code inside its functions.

Headstart splits each dependency's analysis in two. Once the interface half is done, an early metadata file is written and dependents begin. For cargo check, they run all the way to completion on that early metadata. For cargo build, they complete their analysis on it but pause before code generation until the dependency's full metadata appears, releasing their scheduler slot for other work while they wait.

Two flags, nine patches

On the compiler side, -Zearly-metadata arrives as six patches. A new analysis_interfaces query divides analysis into item interfaces and function bodies; the driver writes a .early-rmeta file between those two phases; and crate loading can accept early metadata, then substitute the complete version before code generation, blocking on a lock the producer holds until the file is written.

Cargo's -Zheadstart consists of three patches: it forwards the compiler flag to every compilation, starts dependents when the early-metadata notification arrives, reassigns the slots of paused jobs, and withholds a crate's output until every dependency has succeeded. The author presents the whole set as a commit series, each patch with its own message and tests, intended to become upstream pull requests.

Measured gains and their limits

The measured projects include rust-analyzer, zed, bevy, lemmy and polars. Combining headstart with the parallel front end (-Zthreads=8), which already overlaps some of the same work, adds up to a further 25%.

Because the gains rely on spare cores that a conventional build never uses, they shrink on smaller machines. On 4 cores, rust-analyzer's check is 24% faster and its build 13–15%, codex-rs's check improves 14%, and builds that are already wide show no change.

Correctness and costs

According to the project's documentation, an error in a function body still fails the build with the same diagnostics and exit status as today; only progress lines and the cross-crate ordering of JSON messages can differ. The trade-offs are downstream work that gets discarded when something fails, errors surfacing slightly later, and higher peak memory.

Verification is extensive. One script replays error scenarios — a clean build, a failing dependency, a failing binary — across check and build with the feature on and off, comparing human-readable output, JSON output, exit status and what the built binary prints. Another builds all 53 rustc-perf compile benchmarks in both modes with a -Zearly-metadata-verify option and requires every build to succeed with identical diagnostics. A smoke-test workspace shows the effect directly: a library that takes seconds to check, almost entirely in its bodies, lets its dependent begin about 0.2 seconds in.

Trying it

A setup script checks out, patches and builds both tools. The feature is opt-in per invocation with cargo check -Zheadstart using the patched binaries, or via the environment variable CARGO_UNSTABLE_HEADSTART=true, or an [unstable] headstart = true line in .cargo/config.toml. Without one of those switches the patched cargo behaves like upstream, which the author says makes the same binaries a fair baseline for benchmarking. Design notes, full measurements and a readiness assessment aimed at the compiler and cargo teams are kept in the repository's docs.

Why it matters

Compile time is one of Rust's most persistent complaints, and most relief so far has come from faster hardware, incremental compilation or workspace hygiene. Headstart attacks scheduling inside the toolchain itself, and it does so in a form — a small, tested patch series against rustc and cargo — designed for upstreaming rather than as a parallel build system users must adopt. If it lands, every large workspace benefits without changing a line of code. The caveats are real: the gains depend on idle cores, so heavily loaded CI runners or small laptops will see less, and peak memory use rises. With its explicit readiness notes for the compiler and cargo teams, this reads less like an experiment and more like a preview of a possible upstream feature.