cargo build: Usage, Options & Common CI Errors

Compile a Rust crate and its dependencies - and survive it in CI.

cargo build compiles the current package and all of its dependencies. In CI you almost always want --release for optimized binaries and --locked to fail fast on a stale lockfile.

What it does

Resolves dependencies, compiles the crate graph, and writes artifacts to target/debug (or target/release with --release). It updates Cargo.lock unless you pass --locked or --frozen.

Common usage

cargo build                       # debug build into target/debug
cargo build --release             # optimized build into target/release
cargo build --locked              # fail if Cargo.lock is out of date
cargo build --target x86_64-unknown-linux-musl
cargo build --all-features --workspace

Common CI error: lockfile needs update

With --locked, a drifted Cargo.lock fails the build: "error: the lock file needs to be updated but --locked was passed to prevent this." Fix: run cargo update (or cargo build without --locked) locally and commit the regenerated Cargo.lock, then keep --locked in CI to catch future drift.

Options

Related guides