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:

1. Reproducibility: They ensure the same packages are installed regardless of when or where installation occurs.
2. Consistency: Everyone working on a project installs the exact same dependencies.
3. Security: By pinning specific versions and including file hashes, they prevent supply chain attacks.

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:

1. Single-use lock files: Similar to requirements.txt, serving a single purpose (like development or production dependencies)
2. 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

Several tools have shipped PEP 751 support since the spec was accepted in March 2025:

• pip added an experimental pip lock command in 25.1 (April 2025) that writes pylock.toml files, and added experimental pip install -r pylock.toml in 26.1 (April 2026) for installing from one. Both sides are explicitly experimental: the generated lockfile is only valid for the Python version and platform that produced it, and the install side does not yet support extras or dependency groups. A pip sync command is being discussed (pypa/pip#13737) but has not shipped.
• uv supports reading and exporting PEP 751 lockfiles via uv export --format pylock.toml, while keeping its own cross-platform uv.lock as the primary format.
• PDM supports exporting to PEP 751 alongside its native lockfile.
• Poetry tracks PEP 751 adoption in an open issue and has not shipped support as of April 2026.

Tools that maintain their own native lockfile often treat pylock.toml as an export target rather than a replacement, because per-tool lockfiles can capture information the PEP 751 format does not yet standardize (such as uv’s cross-platform resolution).

Learn More

• PEP 751
• What is a Lockfile?
• Why pylock.toml Includes Digital Attestations