PEP 751 pylock.toml Support

Pipenv supports PEP 751 pylock.toml files, which provide a standardized format for recording Python dependencies to enable installation reproducibility.

What is pylock.toml?

The pylock.toml file is a standardized lock file format introduced in PEP 751. It is designed to be:

  • Human-readable and machine-generated

  • Secure by default (includes file hashes)

  • Able to support both single-use and multi-use lock files

  • Compatible across different Python packaging tools

Using pylock.toml with Pipenv

Pipenv can automatically detect and use pylock.toml files in your project. When both a Pipfile.lock and a pylock.toml file exist, Pipenv will prioritize the pylock.toml file.

Reading pylock.toml Files

When you run commands like pipenv install or pipenv sync, Pipenv will check for a pylock.toml file in your project directory. If found, it will use the dependencies specified in the pylock.toml file instead of Pipfile.lock.

Pipenv looks for pylock.toml files in the following order:

  1. A file named pylock.toml in the project directory

  2. A file matching the pattern pylock.*.toml in the project directory

Example pylock.toml File

Here’s a simplified example of a pylock.toml file:

lock-version = '1.0'
environments = ["sys_platform == 'win32'", "sys_platform == 'linux'", "sys_platform == 'darwin'"]
requires-python = '>=3.8'
extras = []
dependency-groups = ['dev']
default-groups = ['default']
created-by = 'pipenv'

[[packages]]
name = 'requests'
version = '2.28.1'
requires-python = '>=3.7'
index = 'https://pypi.org/simple/'

[[packages.wheels]]
name = 'requests-2.28.1-py3-none-any.whl'
upload-time = '2022-07-13T14:00:00Z'
url = 'https://files.pythonhosted.org/packages/ca/91/6d9b8ccacd0412c08820f72cebaa4f0c61441f4AE7b7338a82051330d70/requests-2.28.1-py3-none-any.whl'
size = 61805
hashes = {sha256 = 'b8aa58f8cf793ffd8782d3d8cb19e66ef36f7aba4353eec859e74678b01b07a7'}

[[packages]]
name = 'pytest'
version = '7.0.0'
marker = "'dev' in dependency_groups"
index = 'https://pypi.org/simple/'

Benefits of Using pylock.toml

  • Standardization: pylock.toml is a standardized format that can be used by multiple Python packaging tools.

  • Security: pylock.toml includes file hashes by default, making it more secure against supply chain attacks.

  • Flexibility: pylock.toml supports extras and dependency groups for multi-use lock files.

  • Interoperability: pylock.toml can be used by different tools, reducing vendor lock-in.

  • Auditability: Packages include their index URL for SBOM generation.

Writing pylock.toml Files

Pipenv can generate pylock.toml files alongside Pipfile.lock files. To enable this feature, add the following to your Pipfile:

[pipenv]
use_pylock = true

With this setting, whenever Pipenv updates the Pipfile.lock file (e.g., when running pipenv lock), it will also generate a pylock.toml file in the same directory.

You can also specify a custom name for the pylock.toml file:

[pipenv]
use_pylock = true
pylock_name = "dev"  # This will generate pylock.dev.toml

CLI Commands

Pipenv provides a pylock command for managing pylock.toml files:

Generate pylock.toml from Pipfile.lock

pipenv pylock --generate

Generate pylock.toml from pyproject.toml

Create a pylock.toml skeleton from your pyproject.toml dependencies (PEP 621/735):

pipenv pylock --from-pyproject

Note: This creates a skeleton file with declared dependencies. Package versions and hashes need to be resolved by running pipenv lock.

Validate pylock.toml

pipenv pylock --validate

Custom Output Path

pipenv pylock --generate --output /path/to/pylock.toml

Custom Dependency Groups

Specify which dependency groups should be used for develop packages:

pipenv pylock --generate --dev-groups "dev,test,docs"

pyproject.toml Support

Pipenv can read dependencies from pyproject.toml files following PEP 621 and PEP 735:

  • [project.dependencies] - Main project dependencies

  • [project.optional-dependencies] - Optional dependencies (extras)

  • [dependency-groups] - Dependency groups (PEP 735)

This allows you to use pyproject.toml as your primary dependency specification while generating standardized pylock.toml files.

Marker Evaluation

Pipenv supports PEP 751 marker syntax for extras and dependency groups:

  • 'name' in extras - Include package when extra is enabled

  • 'name' in dependency_groups - Include package when dependency group is enabled

Example:

[[packages]]
name = 'pytest'
version = '7.0.0'
marker = "'dev' in dependency_groups"

Features

Implemented

  • ✅ Core pylock.toml format (read/write)

  • ✅ Bidirectional conversion with Pipfile.lock

  • ✅ Package index tracking (packages.index)

  • ✅ Extras and dependency groups

  • ✅ Marker evaluation for filtering packages

  • ✅ CLI commands for generation and validation

  • ✅ pyproject.toml dependency reading

Future Enhancements

  • VCS package support (packages.vcs)

  • Local directory support (packages.directory)

  • Direct archive support (packages.archive)

  • Attestation identities support