pip-tools

Common errors

• 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: 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: 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>`).

• 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

• 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