Chapter 1 · Practice 4 of 5
Commit a lockfile so every install is the same
Why it matters
pyproject.toml says which versions are allowed. A lockfile records which exact versions were resolved, including every transitive dependency. Without one, a new release of a package three levels down can change your production build on a Tuesday afternoon.
With uv, uv.lock is a universal lockfile that covers every platform and Python version, and the uv docs say it should be checked into version control. Do not edit it by hand.
| Command | What it does |
|---|---|
uv sync --locked | Fails if the lockfile is out of date. Use it in CI. |
uv lock --upgrade-package httpx | Upgrades one package and keeps the rest |
uv export | Writes requirements.txt or pylock.toml for other tools |
If you use pip, pip-tools or another tool, the rule is the same: generate a pinned file, commit it and install from it in CI and in production.
Avoid
- Unpinned
pip installin Dockerfiles and CI jobs - Hand-editing
uv.lockto fix a conflict - Upgrading every dependency at once to fix one bug