# What is a lockfile?

A lockfile is a text file enumerating the specific version of every dependency used by a project; it serves as a contract that guarantees reproducible environments across different systems and time periods.

A lockfile might record:

* Exact versions of all direct and transitive dependencies
* Cryptographic hashes to verify package integrity
* Platform-specific requirements and constraints
* Metadata about how dependencies were resolved

This creates a "single source of truth" for project dependencies that can be reliably reproduced.

The Python ecosystem lacked standardized lockfile support until [PEP 751](https://pydevtools.com/handbook/explanation/what-is-pep-751.md) was accepted in March 2025. Before that, each tool developed its own format:

* `poetry.lock` from [Poetry](https://pydevtools.com/handbook/reference/poetry.md)
* `Pipfile.lock` from [Pipenv](https://pydevtools.com/handbook/reference/pipenv.md)
* `pdm.lock` from [PDM](https://pydevtools.com/handbook/reference/pdm.md)
* `uv.lock` from [uv](https://pydevtools.com/handbook/reference/uv.md)
* Requirements files with hashes from [pip-tools](https://pydevtools.com/handbook/reference/pip-tools.md)
* `pylock.toml` from [pip](https://pydevtools.com/handbook/reference/pip.md) 25.1+ via the experimental `pip lock` command (single-platform only)

Several of these tools also support writing or reading PEP 751's `pylock.toml` format alongside their native lockfile, so a project's primary lockfile and its shareable export can now be different files.


## Lockfiles and security fixes

When a vulnerability is disclosed in a dependency, the lockfile is where the fix happens. The application deployer upgrades the affected package in their lockfile, not in the version specifiers of every library that transitively depends on it.

Most tools support targeted upgrades that re-resolve a single package without touching the rest of the dependency tree:

```bash
uv lock --upgrade-package urllib3
```

```bash
pip-compile --upgrade-package urllib3
```

```bash
poetry update urllib3
```

After upgrading, run a vulnerability scan (`uv audit` or `pip-audit`) to confirm the fixed version landed in the lockfile. This workflow keeps version specifiers in libraries focused on compatibility while giving application deployers direct control over which versions ship to production.

## Learn More

* [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)
* [PEP 751 – A file format to record Python dependencies for installation reproducibility](https://peps.python.org/pep-0751/)