cargo build --locked: fail if Cargo.lock needs to be updated

cargo build --locked requires Cargo.lock to be up to date: if Cargo would have to add, remove or change any entry, the build stops with an error instead of rewriting the lockfile. Use it in CI and release builds so the binary is compiled with exactly the dependency versions that were committed. --frozen adds --offline on top, and cargo install --locked makes installs use the crate's own lockfile.

A stale lockfile

First without any lockfile, then with a path dependency added to Cargo.toml after Cargo.lock was generated (no network is needed):

cargo new -q --vcs none app && cd app
cargo new -q --vcs none --lib util
echo "--- no Cargo.lock yet"
cargo build -q --locked 2>&1 | sed -E 's#[^ ]*Cargo[.]lock#Cargo.lock#'; echo "exit: ${PIPESTATUS[0]}"
cargo build -q; echo "plain build writes Cargo.lock, exit: $?"
cat >> Cargo.toml <<'EOT'
util = { path = "util" }
EOT
echo "--- cargo build --locked after adding a dependency"
cargo build -q --locked 2>&1 | sed -E 's#[^ ]*Cargo[.]lock#Cargo.lock#'; echo "exit: ${PIPESTATUS[0]}"
cargo build -q; echo "plain build updates Cargo.lock, exit: $?"
cargo build -q --locked; echo "locked again, exit: $?"

--- no Cargo.lock yet
error: cannot create the lock file Cargo.lock because --locked was passed to prevent this
help: to generate the lock file without accessing the network, remove the --locked flag and use --offline instead.
exit: 101
plain build writes Cargo.lock, exit: 0
--- cargo build --locked after adding a dependency
error: cannot update the lock file Cargo.lock because --locked was passed to prevent this
help: to generate the lock file without accessing the network, remove the --locked flag and use --offline instead.
exit: 101
plain build updates Cargo.lock, exit: 0
locked again, exit: 0

Both cases exit with 101: Cargo may neither create a missing lockfile nor add the new entry. A plain build does either, after which --locked passes. The sed shortens the absolute lockfile path.

The three flags

All Cargo commands that resolve dependencies accept them: build, check, test, run, doc, install, fetch, package. The environment variable CARGO_NET_OFFLINE=true is the config equivalent of --offline.

cargo install --locked

cargo install ripgrep --locked

Without --locked, cargo install re-resolves the crate's dependencies to their newest semver-compatible versions, so an install can fail or behave differently from the author's release build. Many projects document --locked in their install instructions for that reason.

CI recipe

cargo fetch --locked          # download exactly what Cargo.lock lists
cargo build --frozen --release
cargo test --frozen

cargo fetch warms the cache with network access; the build and tests then run without it.

Pitfalls

• A Rust toolchain upgrade can change the lockfile format version; an old toolchain in CI then sees the lockfile as needing changes. Pin the toolchain with rust-toolchain.toml.
• --locked with a missing Cargo.lock fails too, as the first run shows, so commit the lockfile before turning the flag on in CI.
• Workspaces share one Cargo.lock at the root; editing any member's Cargo.toml can make --locked fail for the whole workspace.
• The flag does not check for yanked or vulnerable versions; use cargo audit for that.

FAQ