Install & Compatibility
Where this runs
tested against v7.6.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.000s · 21MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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>`.
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
pip-compile --version
Debug
Known issues
breakingpip-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.fixUpgrade to Python >=3.9 or pin pip-tools to a version <7.5.0.
affects: >=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.fixTo 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`.
affects: All versions
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.fixBe 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.
affects: All versions
gotchaDue 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.fixIf 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.
affects: Intermittent, often with new pip releases
gotchaFor 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.fixConsider 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.
affects: All versions (as an alternative)
breakingThe `pip-compile` and `pip-sync` commands are command-line utilities and must be executed in a shell environment. Attempting to run them directly as lines of code within a Python script (without using `subprocess` or similar methods) will result in a `SyntaxError`.fixEnsure `pip-compile` and `pip-sync` are invoked as shell commands (e.g., directly in a terminal, or via `subprocess.run()` from a Python script if orchestrating) and not directly interpreted by the Python interpreter.
affects: All versions
breakingThe `pip-compile` and `pip-sync` commands are standalone executables and should be run from the command line (shell) or invoked via Python's `subprocess` module. They cannot be directly embedded as statements within a Python script.fixExecute `pip-compile` and `pip-sync` directly from your shell/terminal. If integrating into a Python script, use `subprocess.run(['pip-compile', 'requirements.in'], check=True)`.
affects: All versions
Upgrade
Version history
7.6.1latest on PyPI · released Aug 12, 2026
Audit
Dependencies
piprequiredCore functionality relies on pip.