pip-tools

pip-tools provides a set of command-line tools designed to keep pip-based packages fresh while maintaining predictable and deterministic builds. It primarily consists of two tools:

• pip-compile: Used to resolve dependencies and generate a pinned requirements file.
• pip-sync: Used to synchronize your virtual environment with the pinned requirements file.

You can define project-level defaults for pip-compile and pip-sync by writing them to a configuration file. This allows you to avoid repeating command-line flags.

Configuration files are looked up in the following order:

1. Any path explicitly passed via the --config flag.
2. .pip-tools.toml in the directory of the input file.
3. pyproject.toml in the directory of the input file.

If you are piping input from stdin, the current working directory is used for lookup.

To bypass configuration files entirely, use the --no-config flag.

Use pip-compile to generate a pinned requirements.txt file from dependency specifications in pyproject.toml, setup.cfg, setup.py, or requirements.in.

Important: Run pip-compile within the same virtual environment as your project to ensure environment markers and conditional dependencies resolve correctly relative to your project's environment.

If an existing requirements.txt is found that satisfies the dependencies, pip-compile will make no changes. To compile from scratch, delete the existing file or use the --upgrade flag.

pip-compile requirements.in

To change the command name displayed in the autogenerated header of the requirements file, set the CUSTOM_COMPILE_COMMAND environment variable.

$ CUSTOM_COMPILE_COMMAND="./pipcompilewrapper" pip-compile requirements.in

Use pip-sync to synchronize your virtual environment with a requirements.txt file. It will install, upgrade, or uninstall packages to ensure the environment matches the file exactly.

Warning: pip-sync is intended to be used only with files generated by pip-compile. It will not upgrade or uninstall packaging tools like setuptools, pip, or pip-tools itself.

To update your pinned dependencies, use the following flags:

• --upgrade / -U: Upgrade all packages in the existing requirements.txt to the latest versions that satisfy the constraints.
• --upgrade-package <package> / -P <package>: Upgrade only a specific package (or a specific version of a package).

You can combine these to upgrade everything while constraining certain packages.

To use pip-tools, you must install it within your project's virtual environment. This ensures that the tools are available to manage the specific dependencies of that environment.

1. Activate your virtual environment.
2. Install the package using python -m pip install pip-tools.

$ source /path/to/venv/bin/activate
(venv) $ python -m pip install pip-tools

Configuration is organized into three distinct sections within a TOML file. Use [tool.pip-tools] for global settings, [tool.pip-tools.compile] for settings specific to pip-compile, and [tool.pip-tools.sync] for settings specific to pip-sync.

Note: The documentation shows [tool.pip-tools.pip-sync] in the example, but the section definition lists [tool.pip-tools.sync]. Follow the section definitions for correct scoping.

[tool.pip-tools]
# configuration for pip-compile and pip-sync

[tool.pip-tools.compile]
# configuration specific to pip-compile

[tool.pip-tools.sync]
# configuration specific to pip-sync

The pip-compile command generates a pinned requirements.txt file from source dependency files such as requirements.in, pyproject.toml, setup.cfg, or setup.py.

By default, it looks for requirements.in. If multiple source files are provided, you must specify an --output-file.

Common usage patterns:

• Basic compilation: pip-compile (compiles requirements.in to requirements.txt)
• Upgrade all packages: pip-compile --upgrade
• Upgrade specific packages: pip-compile -P django -P requests
• Include security hashes: pip-compile --generate-hashes
• Compile with extras: pip-compile --extra dev pyproject.toml

The following behaviors are changing in future major releases:

• --allow-unsafe will be enabled by default. Use --no-allow-unsafe to maintain current behavior.
• --strip-extras will be enabled by default. Use --no-strip-extras to maintain current behavior.
• The legacy resolver is deprecated and will be removed.

Use the --pip-args option to forward any valid pip flags or arguments to the underlying pip command.

$ pip-compile requirements.in --pip-args "--retries 10 --timeout 30"