Description

<!-- pyml disable-next-line first-line-heading --> [![jazzband-image]][jazzband] [![pypi][pypi-image]][pypi] [![pyversions][pyversions-image]][pyversions] [![pre-commit][pre-commit-image]][pre-commit] [![buildstatus-gha][buildstatus-gha-image]][buildstatus-gha] [![codecov][codecov-image]][codecov] [![Matrix Room Badge]][Matrix Room] [![Matrix Space Badge]][Matrix Space] [![discord-chat-image]][discord-chat] # pip-tools = pip-compile + pip-sync A set of command line tools to help you keep your `pip`-based packages fresh, even when you've pinned them. You do pin them, right? (In building your Python application and its dependencies for production, you want to make sure that your builds are predictable and deterministic.) [![pip-tools overview for phase II][pip-tools-overview]][pip-tools-overview] ## Installation Similar to `pip`, `pip-tools` must be installed in each of your project's [virtual environments](https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments): ```console $ source /path/to/venv/bin/activate (venv) $ python -m pip install pip-tools ``` **Note**: all of the remaining example commands assume you've activated your project's virtual environment. ## Example usage for `pip-compile` The `pip-compile` command lets you compile a `requirements.txt` file from your dependencies, specified in either `pyproject.toml`, `setup.cfg`, `setup.py`, or `requirements.in`. Run it with `pip-compile` or `python -m piptools compile` (or `pipx run --spec pip-tools pip-compile` if `pipx` was installed with the appropriate Python version). If you use multiple Python versions, you can also run `py -X.Y -m piptools compile` on Windows and `pythonX.Y -m piptools compile` on other systems. `pip-compile` should be run from the same virtual environment as your project so conditional dependencies that require a specific Python version, or other environment markers, resolve relative to your project's environment. **Note**: If `pip-compile` finds an existing `requirements.txt` file that fulfils the dependencies then no changes will be made, even if updates are available. To compile from scratch, first delete the existing `requirements.txt` file, or see [Updating requirements](#updating-requirements) for alternative approaches. ### Requirements from `pyproject.toml` The `pyproject.toml` file is the [latest standard](https://peps.python.org/pep-0621/) for configuring packages and applications, and is recommended for new projects. `pip-compile` supports both installing your `project.dependencies` as well as your `project.optional-dependencies`. Thanks to the fact that this is an official standard, you can use `pip-compile` to pin the dependencies in projects that use modern standards-adhering packaging tools like [Setuptools](https://setuptools.pypa.io), [Hatch](https://hatch.pypa.io/) or [flit](https://flit.pypa.io/). Suppose you have a 'foobar' Python application that is packaged using `Setuptools`, and you want to pin it for production. You can declare the project metadata as: ```toml [build-system] requires = ["setuptools", "setuptools-scm"] build-backend = "setuptools.build_meta" [project] requires-python = ">=3.9" name = "foobar" dynamic = ["dependencies", "optional-dependencies"] [tool.setuptools.dynamic] dependencies = { file = ["requirements.in"] } optional-dependencies.test = { file = ["requirements-test.txt"] } ``` If you have a Django application that is packaged using `Hatch`, and you want to pin it for production. You also want to pin your development tools in a separate pin file. You declare `django` as a dependency and create an optional dependency `dev` that includes `pytest`: ```toml [build-system] requires = ["hatchling"] build-backend = "hatchling.build" [project] name = "my-cool-django-app" version = "42" dependencies = ["django"] [project.optional-dependencies] dev = ["pytest"] ``` You can produce your pin files as easily as: ```console $ pip-compile -o requirements.txt pyproject.toml # # This file is autogenerated by pip-compile with Python 3.10 # by the following command: # # pip-compile --output-file=requirements.txt pyproject.toml # asgiref==3.6.0 # via django django==4.1.7 # via my-cool-django-app (pyproject.toml) sqlparse==0.4.3 # via django $ pip-compile --extra dev -o dev-requirements.txt pyproject.toml # # This file is autogenerated by pip-compile with Python 3.10 # by the following command: # # pip-compile --extra=dev --output-file=dev-requirements.txt pyproject.toml # asgiref==3.6.0 # via django attrs==22.2.0 # via pytest django==4.1.7 # via my-cool-django-app (pyproject.toml) exceptiongroup==1.1.1 # via pytest iniconfig==2.0.0 # via pytest packaging==23.0 # via pytest pluggy==1.0.0 # via pytest pytest==7.2.2 # via my-cool-django-app (pyproject.toml) sqlparse==0.4.3 # via django tomli==2.0.1 # via pytest ``` This is great for both pinning your applications, but also to keep the CI