skip to content

Why is `cargo check` faster than `cargo build`, and which kinds of errors can `cargo check` miss?

level: middleimportance: must knowfreq 58%

answer

  1. stops before the back end
  2. metadata files, no machine code
  3. nothing is linked
  4. errors raised while instantiating generics

basics

~20 s

cargo check runs the compiler's analysis, including type and borrow checking, but skips code generation and linking, emitting only metadata. Errors that surface during code generation or linking, such as a missing native symbol, appear only with cargo build.

solid answer

~40 s

`cargo check` compiles each crate in the graph only as far as the compiler's analysis: parsing, macro expansion, name resolution, type checking and borrow checking. With `-v` you can see Cargo pass `--emit=dep-info,metadata` to rustc, so the package and its dependencies produce `.rmeta` files instead of `.rlib`s, no executable is linked, and code generation, usually the slowest phase, never runs. Build scripts and procedural macros are the exception, because they must actually execute. The Cargo docs warn about the cost: some diagnostics are only emitted during code generation. A constant that panics only when a generic is instantiated with a particular value (E0080) and a native symbol the linker cannot find both pass `cargo check` and fail `cargo build`. A plain `cargo check` also covers only the library and binaries.

code

rust · 15 lines
rust
struct NonEmpty<const N: usize>;

impl<const N: usize> NonEmpty<N> {
    const OK: () = assert!(N > 0, "buffer size must be non-zero");
}

fn make_buffer<const N: usize>() -> [u8; N] {
    let () = NonEmpty::<N>::OK;
    [0; N]
}

fn main() {
    let buf = make_buffer::<0>();
    println!("{}", buf.len());
}

go deeper

for a junior

Know that cargo check reports compile errors without producing a binary, and that it is the quick command to run while editing.

for a middle

Explain where the time goes: check stops after analysis and emits metadata, skipping code generation and linking, while build scripts and proc macros still run.

for a senior

Name the errors check cannot see, such as link failures and errors raised while instantiating generics, and keep a real build or test as the gate before merging.

for a principal

Weigh where check fits a team's loop and pipeline: fast feedback on save, never the only CI step, and build scripts or proc macros as the first place to look when it is slow.

## What `cargo check` actually runs The Rust compiler works in two broad halves. The **front end** parses source, expands macros, resolves names, infers and checks types and runs the borrow checker. The **back end** generates machine code, through LLVM by default, and the linker then joins the object files into a library or an executable. In a typical build, much of the time goes to the back end and the linker. `cargo check` runs the front end and stops. The Cargo documentation describes it as compiling the packages "without performing the final step of code generation, which is faster than running cargo build", and it notes that the compiler saves **metadata** files so later runs can reuse them. Most of what a developer needs from the edit loop, the type errors, borrow errors, unresolved imports and most lints, comes from the front end, so `cargo check` answers "does this compile?" in a fraction of a build's time. ## The evidence in the target directory Running both commands with `-v` shows the difference in the flags Cargo hands to rustc: | | `cargo check` | `cargo build` | |---|---|---| | rustc output requested | `--emit=dep-info,metadata` | `--emit=dep-info,link` for a binary, `--emit=dep-info,metadata,link` for a library | | Files left in `target/debug/deps` | `.rmeta` metadata only | `.rlib` libraries and the executable | | Dependencies | also checked to metadata only | compiled to `.rlib` | | Build scripts and proc macros | compiled to native code and run | compiled to native code and run | | Linking | none | the final executable is linked | Two consequences follow. First, a build script or a procedural macro still costs real compile time under `cargo check`, because it has to execute to produce code or settings for the crate being checked. Second, `cargo check` artifacts are only a small head start for `cargo build`: after a check, a build compiles the package and every library dependency again, because metadata alone cannot be linked. Only the build scripts, already compiled and run, were reused in the run behind this answer. ## Errors only `cargo build` reports The Cargo docs say it plainly: "Some diagnostics and errors are only emitted during code generation, so they inherently won't be reported with cargo check." Two kinds come up in practice: 1. **Errors found while instantiating generics.** Generic code is turned into concrete code, monomorphized, during code generation. An associated constant that asserts on a const parameter, like `NonEmpty::<N>::OK` in the code example, is only evaluated for the concrete `N` that a caller uses. `cargo check` finishes cleanly on that file; `cargo build` stops with `error[E0080]: evaluation panicked: buffer size must be non-zero` and a note that it was encountered while instantiating `fn make_buffer::<0>`. 2. **Link errors.** An `unsafe extern "C"` block can declare a C function that no linked library provides. The declaration type-checks, so `cargo check` passes, and `cargo build` fails with "linking with `cc` failed" and an undefined-symbols report from the linker. Missing native libraries, wrong link search paths and duplicate symbols all live here. Neither is a reason to avoid `cargo check`; they are a reason to make `cargo build` or `cargo test` the step that gates a merge. ## What a plain `cargo check` covers With no target flags, `cargo check` checks "all binary and library targets" of the selected packages, and skips binaries whose `required-features` are missing. Integration tests in `tests/`, examples and benchmarks are not checked, and neither is code under `#[cfg(test)]`. To widen it: - `cargo check --tests` checks the targets that have tests, compiled as tests. - `cargo check --all-targets` adds examples and benchmarks as well. - `cargo check --release` or `--profile NAME` checks with another profile's settings, which matters when code depends on `debug_assertions`. ## Using check well - Keep `cargo check` as the fast inner loop, and many editors run it on save for exactly this reason. - Run `cargo build` or `cargo test` before declaring the work done, since only they reach code generation and the linker. - Do not run `cargo check` in CI as a cheap stand-in for building, unless a later step builds anyway. - When a check is still slow, look at build scripts and procedural macros first: they are the parts that `cargo check` cannot skip.

  • Does running `cargo check` first make the following `cargo build` faster?
    Only slightly. `cargo check` leaves metadata-only `.rmeta` files, which cannot be linked, so the next `cargo build` compiles the package and every library dependency again. In the run behind this answer, only the build scripts, already compiled and executed by the check, were reused. Check speeds up the edit loop, not the build that follows it.
  • How do you make `cargo check` cover integration tests and benchmarks too?
    Add a target flag. `cargo check --tests` checks the targets that have tests, including `tests/*.rs` and `#[cfg(test)]` code, and `cargo check --all-targets` adds examples and benchmarks. A type error in `tests/cli.rs` passes a plain `cargo check` and fails `cargo check --all-targets` with its E0308.
  • Why can `cargo check` still be slow on a crate that uses heavy procedural macros or a build script?
    Build scripts and procedural macros are programs that must run before the crate can be analysed, so `cargo check` compiles them to native code and executes them, exactly as `cargo build` does. Only the checked crates themselves stop at metadata.

Proofreading a manuscript versus sending it to the printer: the proofreader catches grammar and logic errors quickly, but only the print run discovers that a plate is missing or two pages will not bind together.

  • cargo check builds a debug binary and only skips the optimizer
  • if cargo check passes, cargo build is guaranteed to succeed
  • cargo check skips borrow checking to save time
  • cargo check does not compile or run build scripts
  • a plain cargo check type-checks integration tests and benchmarks