Skip to content

What is PEP 751?

by Tim Hopper · Markdown
Packaging

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 lockfiles 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 lockfiles, 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 lockfile standard, tooling has been fragmented, creating issues with portability and vendor lock-in. Different tools couldn’t easily consume each other’s lockfiles, forcing developers to choose a single ecosystem or manage complex conversions.

Key Features of PEP 751

The PEP 751 lockfile 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 lockfiles
  • 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 lockfiles:

  1. Single-use lockfiles: Similar to requirements.txt, serving a single purpose (like development or production dependencies)
  2. Multi-use lockfiles: 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.
  • Cloudflare’s pywrangler uses uv to resolve a Python Workers project’s dependencies into pylock.toml, then installs from that file. In this workflow, pylock.toml is the project’s primary lockfile rather than an export.
  • PDM can export its native pdm.lock to PEP 751 or use pylock.toml directly as the project’s lockfile through its opt-in pylock format.
  • Poetry tracks PEP 751 adoption in an open issue and has not shipped support as of April 2026.

Some tools treat pylock.toml as an export target because their own formats capture information that PEP 751 does not standardize. uv takes this approach to preserve its cross-platform resolution, while PDM and pywrangler can use pylock.toml directly as a project’s primary lockfile.

Last updated on