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.

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 matches pyproject.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

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) and uv sync --locked (strict lockfile usage)