Python Adopts Standard Lock File Format for Reproducible Installs

Python has officially standardized a lock file format.

PEP 751 introduces pylock.toml, a TOML-based format that records exact dependency versions, file hashes, and installation sources. This is a major step forward for achieving reliable, reproducible Python environments, especially in deployment and CI settings.

The PEP was accepted on March 31, 2025. It brings Python in line with ecosystems like JavaScript (package-lock.json), Rust (Cargo.lock), and Go (go.sum), which already rely on standardized lock files.

Unifying Python’s Fragmented Tooling#

Until now, Python had no standard way to lock dependency versions and sources across environments. Projects relied on tools like pip freeze, Poetry, PDM, pip-tools, or uv, each with their own lock file format, leading to:

• Inconsistent tooling
• Vendor lock-in
• Security gaps (e.g., optional hash validation)
• Broken reproducibility between machines and CI/CD pipelines

PEP 751 aims to unify the ecosystem around a single format: pylock.toml.

What’s in pylock.toml?#

The new lock file format is designed to be machine-generated but human-readable. It records everything an installer needs to perform a reproducible install, including:

• Exact package versions
• File hashes and sizes
• Wheel or sdist download locations
• Python version and platform constraints
• Extras and dependency groups
• Audit and provenance info (e.g., VCS commit, upload time)

The format also eliminates the need for dependency resolution during installation, allowing for faster and more predictable installs.

The Python community already had a de facto lock file in requirements.txt, widely used and supported by tools like pip, pip-tools, and Poetry. But it was never formally standardized, which was part of the problem.

The proposal explains that they opted not to standardize on requirements.txt because the format was designed specifically for pip’s needs, making it inflexible and hard to extend. It lacks a formal specification, relies on conventions, and doesn’t support features like dependency groups or platform-specific logic in a structured way. Most critically, it isn’t secure by default: file hashes are optional, and pip doesn’t restrict installs to what's listed unless explicitly told to do so.

In contrast, pylock.toml is designed from the ground up to be auditable, reproducible, and tool-agnostic—with security and multi-environment support baked in.

Impact on Tooling#

Under this new system, tools fall into two categories:

• Lockers: Tools like Poetry, PDM, and uv that generate lock files
• Installers: Tools (including pip or cloud services) that consume lock files and install packages

Because the format is standardized and self-contained, installers don’t need to perform any resolution. They simply install what the lock file specifies. That also means cloud platforms or security scanners can more easily support Python environments without needing to interpret half a dozen formats.

The PEP allows for both single-use and multi-use lock files, supporting complex setups like monorepos and conditional dependencies via extras and dependency groups.

Better Supply Chain Security#

PEP 751 adopts a security-first stance by requiring:

• File hashes and sizes for verification
• Explicit package sources and upload times
• Compatibility declarations for Python versions and platforms

While the PEP doesn't address all supply chain threats (such as typosquatting, maintainer account compromise, and concealed payloads), it lays the groundwork for better auditing and tamper resistance.

Key Differences from requirements.txt

While requirements.txt remains useful, especially for specifying install-time options like --index-url—it lacks many of the guarantees that pylock.toml offers. Here’s how they compare:

PEP 751 is a big step toward modern, secure, and reliable Python packaging. Its adoption promises better reproducibility and auditability, especially in cloud and CI environments. In 2025, we could potentially see support for pylock.toml become a key differentiator for packaging tools, marking a turning point in the effort to end lock file fragmentation across the Python ecosystem.