uv lock --check: Verify the Lockfile Is Current
uv lock --check verifies that uv.lock is already up to date with pyproject.toml without modifying it.
uv lock --check is the CI gate that catches a developer who edited pyproject.toml but forgot to re-lock. It fails the build instead of silently re-resolving.
What it does
uv lock --check (also written uv lock --locked) re-derives what the lockfile should be and exits non-zero if uv.lock differs, leaving the file untouched. It asserts the lock is current rather than updating it.
Common usage
uv lock --check
uv lock --locked
# many jobs use sync with --frozen for the same guarantee
uv sync --frozenOptions
| Flag | What it does |
|---|---|
| --check | Verify the lock is current, do not write it |
| --locked | Synonym asserting the lockfile is up to date |
| --frozen (on sync) | Install from the lock without re-locking or checking |
| --offline | Run without network access |
In CI
Add uv lock --check as an early job step so a stale lockfile fails fast with a clear message. Use --frozen on uv sync in install steps so they never silently regenerate the lock. The two together guarantee CI installs exactly the committed, reviewed dependency set.
Common errors in CI
"error: The lockfile at uv.lock needs to be updated, but --locked was provided. To update the lockfile, run uv lock." means pyproject.toml drifted; run uv lock locally and commit. With --frozen the message is "needs to be updated, but --frozen was provided". "Unable to find lockfile" means uv.lock was never committed.