pip-tools

Warnings

• breaking pip-tools 7.5.x and later versions have dropped support for Python 3.8. Projects still using Python 3.8 will need to use an older version of pip-tools or upgrade their Python version.
  Fix: Upgrade to Python >=3.9 or pin pip-tools to a version <7.5.0.
• gotcha `pip-compile` by default will not update packages if the existing `requirements.txt` file already fulfills the dependencies specified in `requirements.in`. This means simply re-running `pip-compile` won't update to newer versions.
  Fix: To update all packages to their latest compatible versions, use `pip-compile --upgrade requirements.in`. To update a specific package, use `pip-compile --upgrade-package <package_name> requirements.in`.
• gotcha `pip-sync` will aggressively synchronize the active virtual environment to exactly match the `requirements.txt` file. This means any packages present in the environment but not listed in `requirements.txt` will be uninstalled.
  Fix: Be aware that `pip-sync` is more powerful than `pip install -r` for ensuring exact environments. Only use `pip-sync` with `requirements.txt` files generated by `pip-compile` to avoid unexpected removals. Ensure you are in the correct virtual environment.
• gotcha Due to rapid development in `pip` itself, `pip-tools` can sometimes experience temporary incompatibilities with the latest `pip` versions (e.g., `pip` 25.3 caused issues with `pip-tools > 7.5.0`). While `pip-tools` maintainers work to catch up, this can lead to build failures.
  Fix: If encountering issues, try pinning your `pip` version (e.g., `pip install 'pip<25.3'`) until `pip-tools` releases a compatible update. Check the `pip-tools` GitHub issues for ongoing compatibility discussions.
• gotcha For new Python projects, `uv` is being actively recommended by external sources as a faster, drop-in replacement for `pip-tools`' `pip-compile` and `pip-sync` functionalities.
  Fix: Consider evaluating `uv` (available via `pip install uv`) for new projects if performance is a critical concern, though `pip-tools` remains a robust and widely used solution.

Install

• pip install pip-tools Install pip-tools

Imports

• pip-tools CLI

  pip-compile requirements.in

  pip-tools is primarily a command-line interface tool; direct Python programmatic imports are not common for typical usage. Commands are run via the shell or `python -m piptools <command>`.

Quickstart

The typical workflow involves defining your top-level dependencies in a `requirements.in` file (or `pyproject.toml`), then using `pip-compile` to generate a fully-pinned `requirements.txt`. Finally, `pip-sync` is used to install, upgrade, and remove packages in your virtual environment to precisely match the generated `requirements.txt` file. Remember to activate your virtual environment before running `pip-tools` commands.

# 1. Create your input file (e.g., requirements.in)
# requirements.in
# requests
# black~=23.0

# 2. Compile your requirements to a pinned requirements.txt
pip-compile requirements.in

# The above generates a requirements.txt like:
# #
# # This file is autogenerated by pip-compile
# # To update, run:
# #
# #    pip-compile requirements.in
# #
# black==23.12.1 # via -r requirements.in
# certifi==2024.2.2 # via requests
# charset-normalizer==3.3.2 # via requests
# click==8.1.7 # via black
# idna==3.6 # via requests
# mypy-extensions==1.0.0 # via black
# packaging==23.2 # via black
# pathspec==0.12.1 # via black
# platformdirs==4.1.0 # via black
# requests==2.31.0 # via -r requirements.in
# urllib3==2.2.1 # via requests

# 3. Synchronize your virtual environment to match requirements.txt
pip-sync requirements.txt