How to install from a pylock.toml lockfile with pip

A teammate hands you a pylock.toml. Or uv’s uv export --format pylock.toml produces one. Now you need pip to install from it. As of pip 26.1 (April 2026), pip install -r pylock.toml works, with a few caveats worth knowing before you put it in CI.

Confirm pip 26.1 or newer

The -r pylock.toml form was added in pip 26.1. Older pips will treat the file as a regular requirements file and choke on the first TOML line.

python -m pip install --upgrade pip
python -m pip --version

If the version prints anything below 26.1, the rest of this guide will not work.

Install from the lockfile

Point -r at the file the same way you would point it at requirements.txt:

pip install -r pylock.toml

pip prints this warning before it starts installing:

WARNING: Using pylock.toml as a requirements source is an experimental feature. It may be removed/changed in a future release without prior warning.

Every package recorded in the lockfile is then installed at the exact version and hash captured there.

Hash verification is on by default for pylock.toml. If a wheel on disk does not match the sha256 recorded in the file, pip aborts with ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE. instead of installing.

Install only what the lockfile lists

--no-deps tells pip to stop at the lockfile. Without it, pip can install extra dependencies that are not listed in pylock.toml, which defeats the point of locking. If you need the environment to match the lockfile exactly, add --no-deps:

pip install -r pylock.toml --no-deps

Name the file correctly

pip only treats a file as a pylock.toml source when it matches one of two filename patterns:

• pylock.toml
• pylock.<name>.toml (for example pylock.prod.toml, pylock.dev.toml)

Anything else (lockfile.toml, deps.toml) is parsed as a regular requirements file and fails on the first TOML line:

ERROR: Invalid requirement: 'lock-version = "1.0"': Expected semicolon (after name with no version specifier) or end

The named variant is useful when one project ships multiple lockfiles for different environments. Each one is still a pylock file; the name suffix is the only signal pip uses to distinguish them.

Check the current limitations

The pip 26.1 release calls this support experimental:

• Extras and dependency groups in multi-use lockfiles cannot be selected at install time.
• VCS and local-directory entries cannot mix with hash-locked external requirements in the same file.
• Mixing -r pylock.toml with another -r requirements.txt or constraint flag is “strongly discouraged” and likely to change.
• Most resolution flags (--pre, --upgrade, etc.) are ignored. Only --only-binary and --no-binary affect locked requirements.
• Archive file sizes recorded in the lockfile are not validated; only hashes are.
• There is no pip sync yet. Removing packages no longer in the lockfile from an existing environment requires manual cleanup (pypa/pip#13737).

If those constraints rule pip out for now, uv also accepts pylock.toml via uv pip install -r pylock.toml.

Learn More

• What is PEP 751? explains the lockfile format pip is consuming.
• Why pylock.toml includes digital attestations covers the publisher-identity fields you’ll see in the file.
• How to use a uv lockfile for reproducible Python environments shows the uv-side equivalent.
• pip lock command reference covers the lock-generation side.
• What’s new in pip 26.1 walks through the install-side limitations in detail.