What is a lockfile in Python?

A lockfile is a text file that records the exact version of every direct and transitive dependency in a Python project, along with cryptographic hashes. It guarantees that anyone installing the project gets identical package versions.

What is the difference between pyproject.toml and a lockfile?

pyproject.toml declares version ranges for direct dependencies (e.g., `requests>=2.28`). The lockfile pins every resolved dependency to an exact version (e.g., `requests==2.32.3`) so the environment is fully reproducible.

What is PEP 751 and pylock.toml?

PEP 751 is the first Python standard for lockfiles, accepted in March 2025. It defines the `pylock.toml` format so different tools can produce and consume a common lockfile instead of relying on tool-specific formats like poetry.lock or uv.lock.

Does uv create a lockfile?

Yes. uv generates a `uv.lock` file automatically when you run `uv add`, `uv sync`, or `uv lock`. This cross-platform lockfile pins exact versions for all dependencies and can be committed to version control.

What is a lockfile?

by Tim Hopper

Packaging

A lockfile is a text file enumerating the specific version of every dependency used by a project; it serves as a contract that guarantees reproducible environments across different systems and time periods.

A lockfile might record:

Exact versions of all direct and transitive dependencies
Cryptographic hashes to verify package integrity
Platform-specific requirements and constraints
Metadata about how dependencies were resolved

This creates a “single source of truth” for project dependencies that can be reliably reproduced.

The Python ecosystem lacked standardized lockfile support until PEP 751 was accepted in March 2025. Before that, each tool developed its own format:

poetry.lock from Poetry
Pipfile.lock from Pipenv
pdm.lock from PDM
uv.lock from uv
Requirements files with hashes from pip-tools
pylock.toml from pip 25.1+ via the experimental pip lock command (single-platform only)

Several of these tools also support writing or reading PEP 751’s pylock.toml format alongside their native lockfile, so a project’s primary lockfile and its shareable export can now be different files.

Lockfiles and security fixes

When a vulnerability is disclosed in a dependency, the lockfile is where the fix happens. The application deployer upgrades the affected package in their lockfile, not in the version specifiers of every library that transitively depends on it.

Most tools support targeted upgrades that re-resolve a single package without touching the rest of the dependency tree:

uv lock --upgrade-package urllib3

pip-compile --upgrade-package urllib3

poetry update urllib3

After upgrading, run a vulnerability scan (uv audit or pip-audit) to confirm the fixed version landed in the lockfile. This workflow keeps version specifiers in libraries focused on compatibility while giving application deployers direct control over which versions ship to production.

Learn More

Last updated on May 18, 2026

What is a build frontend?What is a PEP?

Please submit corrections and feedback...