What is PEP 751?
Python Enhancement Proposal 751 (PEP 751) introduces a standardized file format for specifying dependencies to enable reproducible installation in Python environments. This proposal, authored by Brett Cannon and accepted in March 2025, establishes a formal specification for lock files in the Python ecosystem.
Lock files serve a critical purpose in modern software development: they record the exact versions of dependencies needed to reproduce a consistent environment. Until now, the Python ecosystem lacked a standard format for lock files, with tools like PDM, pip freeze, pip-tools, Poetry, and uv each using their own approaches.
Why Lock Files Matter
Lock files solve several key problems in dependency management:
- Reproducibility: They ensure the same packages are installed regardless of when or where installation occurs.
- Consistency: Everyone working on a project installs the exact same dependencies.
- Security: By pinning specific versions and including file hashes, they prevent supply chain attacks.
Tooling has been fragmented without a lock file standard, tooling has been fragmented, creating issues with portability and vendor lock-in. Different tools couldn’t easily consume each other’s lock files, forcing developers to choose a single ecosystem or manage complex conversions.
Key Features of PEP 751
The PEP 751 lock file format (pylock.toml) offers several important features:
- Human-readable TOML format: Makes auditing and debugging easier
- No resolver needed at install time: Simplifies and speeds up installation
- Security by default: Includes file hashes to verify package integrity
- Compatibility with multiple use cases: Supports both single-use and multi-use lock files
- Environment markers support: Handles platform-specific dependencies
- Support for package attestations: Enhances supply chain security
Lock File Structure
The standard defines a TOML-based file with a clear structure:
lock-version = "1.0"
environments = ["sys_platform == 'linux'", "sys_platform == 'win32'"]
requires-python = ">=3.12"
created-by = "tool-name"
[[packages]]
name = "package-name"
version = "1.2.3"
wheels = [
{name = "package-1.2.3-py3-none-any.whl", hashes = {sha256 = "..."}}
]This format captures all necessary information to install dependencies consistently across environments while maintaining human readability.
Single-Use vs. Multi-Use Lock Files
PEP 751 supports two approaches to lock files:
- Single-use lock files: Similar to
requirements.txt, serving a single purpose (like development or production dependencies) - Multi-use lock files: Support multiple use cases through extras and dependency groups within a single file, reducing duplication and coordination challenges
Adoption by Python Packaging Tools
For PEP 751 to make a real difference, it must be implemented by the various Python packaging tools. Tool maintainers of pip, Poetry, PDM, uv, and others will need to update their software to support reading and writing the new pylock.toml format. Some tools may initially only export to this format while maintaining their own internal lock files, while others might fully adopt it as their primary mechanism.