Use the locked flag in CI. It makes uv fail if uv.lock no longer matches your project file, so a stale lock breaks the build. The frozen flag uses the lock file without checking it at all, which is faster but lets drift go unnoticed.
What each option does
The uv documentation describes the sync command as installing the project environment from the lock file. By default the sync is exact, which means packages not in the lock file are removed from the environment.
| Option | Behaviour |
|---|---|
| locked | Errors if the lock file is not up to date, instead of updating it |
| frozen | Uses the lock file as is, without checking it is up to date |
| lock with the check option | Verifies the lock file without rewriting it |
The documentation states that checking the lock file with the check flag is equivalent to the locked flag on other commands.
Why the default is risky in CI
The run command locks and syncs automatically unless told otherwise. On a developer laptop that is convenient. In CI it means the pipeline may rewrite the lock file instead of failing when someone forgot to commit an update. The build then tests a set of packages nobody reviewed.
Note also what a lock file is not: new releases do not make it outdated. Upgrades only happen when you ask for them with the upgrade options, so a lock file that is current can still be weeks old.
A pipeline order that works
- Check the lock file against the project file with the check command. Fail on mismatch.
- Sync with the locked flag so the install matches exactly.
- Run tests.
- Scan the pinned packages for known vulnerabilities.
- Upgrade in a separate, reviewed pull request, not in the build.
Use frozen only where a previous step already verified the lock, such as a container build that runs after the check job and needs speed.
A note on caching
CI caches speed up installs, but a cache restored without checking the lock file can bring back old packages. Key your cache on the lock file contents so any change in the lock produces a fresh install, and consider rebuilding from an empty cache on a schedule.
Try it yourself
Click through it at your own pace, or open it full screen. Watch where a gate stops a change before it merges.
Quick check
Does the locked flag upgrade my packages?
No. It fails if the lock is stale. Upgrades happen only when you ask for them.
Is frozen ever the right choice?
Yes, after a separate step has checked the lock, when you want to avoid repeating that work.
For background on the file itself, see the uv lock file explained. Safeguard's policies and gates can block a pull request on a policy you set, and a free scan covers the pinned set.
Sources
Last reviewed: 19 October 2026.
