In CI, cargo build --locked fails if Cargo.lock is missing or would need to change, so the build uses exactly the dependency versions you committed. --offline stops Cargo using the network, and --frozen means both flags together. Use --locked everywhere, and --frozen where dependencies were fetched in an earlier step.
Definitions from the Cargo manual
The Cargo build documentation describes the three flags like this:
| Flag | What it does |
|---|---|
--locked | Asserts that the exact same dependencies and versions are used as when the existing Cargo.lock was generated. Cargo exits with an error if the lock file is missing, or if Cargo attempted to change it because of a different resolution |
--offline | Prevents Cargo from accessing the network for any reason. It may result in different dependency resolution than online mode, because Cargo restricts itself to crates downloaded locally |
--frozen | Equivalent to specifying both --locked and --offline |
The manual says --locked may be used in environments where deterministic builds are desired, such as in CI pipelines.
Why this matters for a service
A service you deploy is the thing that should be built from reviewed inputs. Without --locked, a build that finds Cargo.toml and Cargo.lock out of step, for example after someone edited a version requirement and forgot to commit the lock file, will quietly resolve new versions and update the lock file in the build environment. The binary you ship then contains versions nobody reviewed or scanned.
With --locked, that situation becomes a failed build and a prompt to fix the commit.
What --locked does not do
It pins versions to the lock file. It does not check that the lock file's contents are safe. A malicious or vulnerable version that was added to the lock file stays there until someone reviews it. Pair it with an advisory scan, and see the posts on cargo-deny settings and cargo audit.
The Cargo FAQ adds a related point for installs: cargo install selects the latest dependencies unless --locked is passed. For tools you install in CI, add it. The earlier post on cargo install --locked covers that case.
Where --offline fits
A common pattern is to fetch once and then build with no network, so that a build step cannot pull something new.
cargo fetch --locked
cargo build --release --frozen
cargo test --frozen
The manual warns that offline mode can resolve differently, which is why --locked travels with it. The cargo fetch command downloads dependencies before going offline.
Steps
- Commit Cargo.lock for every binary and service.
- Add
--lockedto build, test, check and install commands in CI. - Fetch dependencies in one step, then use
--frozenfor later steps if your pipeline allows. - Treat a lock file change in CI as a failure, not something to auto commit.
- Run an advisory scan against the lock file on every pull request.
- Review lock file diffs in code review like any other change.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how the full dependency inventory is built, which is what a locked build makes reliable.
Quick check
Do I need --locked if I commit Cargo.lock?
Yes. Committing the file does not stop Cargo from updating it during a build. The flag turns an unexpected change into an error.
Is --frozen always better than --locked?
Only if everything Cargo needs is already downloaded. Otherwise the build fails for lack of network access. Use --locked as the baseline.
Safeguard dependency scanning and SBOM generation read Cargo.lock, so a locked build and the scan describe the same set of crates, and the free scan is at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
