How to use a uv lockfile for reproducible Python environments
Lockfiles ensure your Python project uses identical dependency versions across different machines and deployments. This guide shows how to use uv’s lockfile system to create reproducible environments.
Creating your first lockfile
Start with a new project:
uv init reproducible-demo
cd reproducible-demo
Add some dependencies:
uv add requests pandas
uv automatically generates uv.lock
with pinned versions of requests
, pandas
, and all their dependencies.
Important
The lockfile should be committed to version control.
How uv sync works with lockfiles
Running uv sync
ensures your environment matches your project configuration:
uv sync
uv’s behavior depends on the lockfile state:
- If
uv.lock
matchespyproject.toml
: Installs exact versions from the lockfile - If lockfile is outdated or missing: Re-resolves dependencies, updates the lockfile (equivalent to
uv lock
), then installs dependencies
Enforcing strict lockfile usage
To guarantee installation from an existing lockfile without updates:
uv sync --locked
Warning
If the lockfile doesn’t match pyproject.toml
, uv will error instead of updating dependencies. This is essential for CI/CD pipelines where you want reproducible builds.
Verifying lockfile status
Check if your lockfile matches your project configuration:
uv lock --check
This validates that uv.lock
is current with pyproject.toml
without making changes.
Manually updating the lockfile
Explicitly update the lockfile without syncing the environment:
uv lock
This resolves dependencies from pyproject.toml
and updates uv.lock
but doesn’t install packages.
Upgrading dependencies
Update all packages to their latest compatible versions:
uv lock --upgrade
Upgrade specific packages while preserving others:
uv lock --upgrade-package requests
uv lock --upgrade-package pandas==2.1.0
These flags also work with uv sync
to update and install in one step:
uv sync --upgrade-package requests
Best practices for reproducible environments
- Always commit
uv.lock
to version control - Use
--locked
in CI/CD to prevent unexpected dependency changes - Run
uv lock --check
before deployments to verify consistency - Regularly upgrade with
uv lock --upgrade
for security updates - Understand the difference between
uv sync
(may update lockfile) anduv sync --locked
(strict lockfile usage)