pip-compile-multi

3.3.0 · active · verified Thu Apr 16

pip-compile-multi is a command-line utility for compiling multiple Python `requirements.in` files into locked `requirements.txt` files. It builds upon `pip-tools` (or `uv`) to manage complex dependency graphs, resolve cross-file conflicts, and ensure deterministic, reproducible environments across different project stages like development, testing, and production. The library is actively maintained, with recent updates, and is currently at version 3.3.0.

Common errors

```
Different developers have different dependency versions or production breaks after redeployment.
```
cause Dependencies are not hard-pinned, leading to variations in installed package versions across environments or over time.

fix Use `pip-compile-multi` to generate explicit, version-locked `.txt` files from your `.in` files. Ensure all environments `pip install -r` only from these `.txt` files.
```
pip-compile-multi fails to resolve dependencies or produces incompatible lock files when multiple `.in` files share transitive dependencies.
```
cause Multiple `.in` files define a common package that `pip-compile-multi` resolves differently for each file, leading to a conflict when they are eventually used together.

fix Run `pip-compile-multi` with the `--autoresolve` flag to ensure a globally consistent dependency resolution across all `.in` files.
```
The content of `requirements.txt` does not reflect recent changes made in `requirements.in`.
```
cause After modifying `requirements.in`, `pip-compile-multi` was not executed, or a `verify` check indicated a mismatch.

fix Execute `pip-compile-multi` to recompile your `.in` files into `.txt` files. Incorporate `pip-compile-multi verify` into your development workflow to catch such discrepancies early.
```
Cannot upgrade a single package or only a subset of packages without affecting all other dependencies.
```
cause Running `pip-compile-multi` by default tries to upgrade all packages to their latest compatible versions.

fix Use the `--upgrade-package <package_name>` option to specify which packages should be upgraded, keeping others at their currently pinned versions.

Warnings

breaking Version 3.3.0 removes support for Python 3.9. Users must upgrade to Python 3.10 or newer.
Fix: Ensure your project runs on Python 3.10 or a later supported version. Update your environment accordingly.
breaking In version 3.0.0, the `--use-cache` and `--skip-constraints` flags were enabled by default. Also, the new CLI entrypoint `requirements` was added, and the `-n, --only-name` option was removed in favor of `-t, --only-path`.
Fix: Review your `pip-compile-multi` command-line arguments and configuration. Adjust scripts to use `--no-use-cache` or `--no-skip-constraints` if previous behavior is desired, use `requirements` instead of `pip-compile-multi` if desired, and replace `-n` with `-t`.
gotcha Without the `--autoresolve` flag, separate `.in` files that share common dependencies might resolve those dependencies to different, incompatible versions. This can lead to unexpected behavior or installation failures if these `.txt` files are used together.
Fix: Always use the `--autoresolve` flag when dealing with interdependent `.in` files (e.g., `test.in` referencing `base.in`). Note that `--autoresolve` requires a single 'source node' (a single `.in` file that directly or indirectly references all others) in your dependency graph.
gotcha It's common for generated `.txt` lock files to become out of sync with their corresponding `.in` input files if changes are made to `.in` files but `pip-compile-multi` is not re-run.
Fix: Integrate `pip-compile-multi verify` into your Continuous Integration (CI) pipeline or as a pre-commit hook to detect and prevent desynchronized lock files.
gotcha Poorly organized dependency groups across `.in` files (e.g., mixing linters with deep learning frameworks) can lead to dependency bloat or unnecessary conflicts.
Fix: Structure your `.in` files logically, grouping dependencies based on their functional role within your project (e.g., `runtime.in`, `dev.in`, `test.in`).

Install

pip install pip-compile-multi Install latest version

Quickstart

This quickstart demonstrates how to set up two common dependency sets: `base` for runtime requirements and `test` for testing, which includes the `base` requirements. It shows how to generate the locked `.txt` files and install them.

# 1. Create a directory for your requirement files
mkdir requirements

# 2. Define your base dependencies in requirements/base.in
# requirements/base.in
# click
# pip-tools

# 3. Define your test dependencies in requirements/test.in
# Include base dependencies using -r
# requirements/test.in
# -r base.in
# pytest

# 4. Run pip-compile-multi to generate locked .txt files
pip-compile-multi

# 5. Install your dependencies using the generated .txt files
pip install -r requirements/base.txt -r requirements/test.txt

view raw JSON →