pip-tools
raw JSON → 7.5.3 verified Tue May 12 auth: no python install: stale
pip-tools is a set of command-line tools, primarily `pip-compile` and `pip-sync`, designed to help manage Python project dependencies by pinning them to exact versions. It aims to ensure deterministic and reproducible builds by generating fully-pinned `requirements.txt` files from abstract `requirements.in` files (or `pyproject.toml`). The library is currently at version 7.5.3 and actively maintained, though its release cadence can sometimes be irregular, with recent updates catching up after periods of inactivity.
pip install pip-tools Common errors
error ERROR: Could not find a version that satisfies the requirement <package_name> (from versions: ...) ↓
cause pip-tools (via pip) could not find a suitable version of a package that satisfies all the declared constraints and dependencies, often due to an incompatible Python version, a typo in the package name, or the package not being available on PyPI.
fix
Check the spelling of the package name, ensure your Python version is compatible with the package, update pip-tools and pip (
pip install --upgrade pip setuptools pip-tools), or try installing a specific version of the package. error ERROR: Cannot install -r requirements.in (...) because these package versions have conflicting dependencies. ↓
cause pip-tools detected a conflict in the dependency tree, meaning different packages listed in your `requirements.in` (or their sub-dependencies) require incompatible versions of the same dependency.
fix
Manually inspect your
requirements.in file to identify the conflicting packages, try to relax version constraints where possible, or use pip-compile --trace to get a more detailed conflict report. You may need to upgrade or downgrade specific conflicting packages. error error: subprocess-exited-with-error ↓
cause This generic error indicates that a subprocess (often a package's build script) failed during installation, commonly due to missing system-level dependencies (like C compilers or specific libraries), an issue with the package's build process, or an incompatibility with your Python environment.
fix
Install any necessary system-level build tools (e.g.,
build-essential on Linux, Xcode command-line tools on macOS, or Visual C++ build tools on Windows). Try upgrading setuptools and wheel (pip install --upgrade setuptools wheel), or install pre-release versions of the package if available (pip install --pre <package>). error bash: pip-compile: command not found ↓
cause The `pip-compile` (or `pip-sync`) command is not found in your system's PATH, which usually means pip-tools is not installed or the directory where its executables reside is not included in the PATH environment variable.
fix
Ensure pip-tools is installed (
pip install pip-tools). If it is, verify that the Python scripts directory (e.g., ~/.local/bin on Linux/macOS or Scripts folder in Python installation on Windows) is included in your system's PATH. You can also try running python -m piptools compile as an alternative. 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.
breaking The `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`. ↓
fix Ensure `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.
breaking The `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. ↓
fix Execute `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)`.
Install compatibility stale last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - - 20.3M
3.10 alpine (musl) - - - -
3.10 slim (glibc) wheel 1.9s - 21M
3.10 slim (glibc) - - - -
3.11 alpine (musl) wheel - - 22.5M
3.11 alpine (musl) - - - -
3.11 slim (glibc) wheel 1.9s - 23M
3.11 slim (glibc) - - - -
3.12 alpine (musl) wheel - - 23.5M
3.12 alpine (musl) - - - -
3.12 slim (glibc) wheel 2.6s - 24M
3.12 slim (glibc) - - - -
3.13 alpine (musl) wheel - - 23.2M
3.13 alpine (musl) - - - -
3.13 slim (glibc) wheel 2.5s - 24M
3.13 slim (glibc) - - - -
3.9 alpine (musl) wheel - - 20.1M
3.9 alpine (musl) - - - -
3.9 slim (glibc) wheel 2.4s - 21M
3.9 slim (glibc) - - - -
Imports
- pip-tools CLI
pip-compile requirements.in
Quickstart last tested: 2026-04-24
# 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