uv.lock is the lockfile uv writes next to pyproject.toml. It records the exact resolved versions for your whole dependency tree across platforms, it should be committed to version control, and uv commands update it, not people editing it by hand.
What it records
The uv documentation describes the lockfile as capturing the packages that would be installed across all possible Python markers, such as operating system, architecture and Python version.
So one file serves a Linux CI runner and a developer on another platform. You do not keep a lock per machine.
Your pyproject.toml states broad requirements. The lockfile records the exact versions that were resolved, which is what an install should reproduce.
Commit it
The docs say the file should be checked into version control. That gives consistent installs across machines, and for an application it means the exact package set is known at deploy time.
The same advice appears in other ecosystems, as covered in commit the lockfile for apps and libraries.
When it changes
- Automatically, during uv commands that use the project environment, namely uv sync and uv run.
- Explicitly, with uv lock.
Because it can change as a side effect of ordinary commands, watch pull requests for lockfile changes you did not expect.
Do not edit it by hand
The file is readable TOML, but uv manages it. The docs say not to edit it manually, and that the format is specific to uv and not usable by other tools.
The standard format
The documentation notes that uv keeps uv.lock because some of its functionality cannot be expressed in the standard pylock.toml format. You can export to pylock.toml with uv export -o pylock.toml if another tool needs one.
One gap to check
The documentation page on the lockfile does not explain the sync flags that make an install fail if the lock is out of date or that skip re-locking. Check the uv sync reference for the current options before wiring them into CI.
A review checklist for lock changes
- Does the diff match a change in pyproject.toml, or is it a refresh you expected?
- Did any package jump a major version?
- Are there new packages you do not recognise? Look up each one.
- Did a package move to a different source or index?
- Does CI pass on a clean environment built from the lock?
Why this matters for security
An exact lock lets you answer, for any commit, what third party code was in the build. That is the baseline for vulnerability scanning and for responding when a package turns out to be compromised.
Safeguard's SBOM and dependency scanning works from the dependencies you run, and a free scan is available at gold.safeguard.sh/scan.
Quick check
Is uv.lock per platform?
No. It captures packages across all Python markers, so one lockfile applies across platforms.
Can other tools read uv.lock?
No. The format is specific to uv. Use uv export to produce pylock.toml for other tools.
Sources
Last reviewed: 19 October 2026.
