venv-patcher

Apply and track patches to packages installed in a Python virtual environment.

📖 Documentation: https://thorsten-klein.github.io/venv-patcher/

What is venv-patcher?

venv-patcher applies patches to packages in your venv. It remembers what it did. So you can list your patches, and undo them at any time.

venv-patcher apply -f patches.yml   # apply your patches
venv-patcher list                   # see what is patched
venv-patcher reset                  # undo all patches

The patches file says which patch goes to which package:

version: 1
patches:
  - package: requests
    path: patches/0001-fix.patch

It can also be TOML, with Python 3.11 or newer. See example.yml and example.toml.

How does it work?

• The first time, it turns the package folder into a git repository, and commits the files as they are.
• It applies each patch with git am (or git apply) as a new commit. Names and dates are fixed, so the commits are the same on every run.
• It records each result in a manifest in the venv's site-packages.
• reset goes back to the first commit.

Install

Install it into the venv you want to patch:

pip install venv-patcher

Python 3.9 and git are needed. It does not run outside a venv. Do not install it with pipx or uv tool: it would patch that tool's own venv. See Install venv-patcher.

Documentation

The full documentation is in doc/, and online at https://thorsten-klein.github.io/venv-patcher/.

• About venv-patcher
• venv-patcher in 5 minutes
• How it works
• Command reference
• The patches file
• Guides: writing patches, pinning, upgrades, CI and more

Contributing

Pull requests are welcome. See Development for the setup and the checks. The short version:

uv sync          # install everything
uv run poe all   # every check CI runs

License

MIT. See LICENSE.