# How to install from a pylock.toml lockfile with pip

A teammate hands you a [`pylock.toml`](https://pydevtools.com/handbook/explanation/what-is-pep-751.md). Or [uv](https://pydevtools.com/handbook/reference/uv.md)'s `uv export --format pylock.toml` produces one. Now you need [pip](https://pydevtools.com/handbook/reference/pip.md) 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.

```bash
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`:

```bash
pip install -r pylock.toml
```

pip prints this warning before it starts installing:

```text
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`:

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

> [!IMPORTANT]
> Use `--no-deps` for CI and any other install that must match the lockfile exactly. The pip 26.1 changelog calls this out: without it, locked requirements can pull in additional non-locked packages.

## 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:

```text
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](https://packaging.python.org/en/latest/specifications/pylock-toml/) 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 package-selection flags (`--pre`, `--abi`, 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](https://github.com/pypa/pip/issues/13737)).

If those constraints rule pip out for now, uv also accepts `pylock.toml` via `uv pip install --pylock pylock.toml` (or `-r pylock.toml`, which routes through the same preview feature and emits an experimental warning).

## Learn More

- [What is PEP 751?](https://pydevtools.com/handbook/explanation/what-is-pep-751.md) explains the lockfile format pip is consuming.
- [Why pylock.toml includes digital attestations](https://pydevtools.com/handbook/explanation/why-pylock-toml-includes-digital-attestations.md) covers the publisher-identity fields you'll see in the file.
- [How to use a uv lockfile for reproducible Python environments](https://pydevtools.com/handbook/how-to/how-to-use-a-uv-lockfile-for-reproducible-python-environments.md) shows the uv-side equivalent.
- [pip lock command reference](https://pip.pypa.io/en/stable/cli/pip_lock/) covers the lock-generation side.
- [What's new in pip 26.1](https://sichard.ca/blog/2026/04/whats-new-in-pip-26.1/) walks through the install-side limitations in detail.