# 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. `pip install -r pylock.toml` works (requires pip 26.1 or newer), with a few caveats worth knowing before you put it in CI.

## Confirm pip 26.1 or newer

pip 26.1 and later accept `-r pylock.toml`. Older pips 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. Without `--no-deps`, 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 pylockfile; the name suffix is the only signal pip uses to distinguish them.

## Check the current limitations

This support is 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 -r pylock.toml`, which routes through a preview feature and prints an experimental warning until you pass `--preview-features pylock`.