hatch-pip-compile

hatch plugin to use pip-compile (or uv) to manage project dependencies and lockfiles.

Usage#

The hatch-pip-compile plugin will automatically run pip-compile whenever your environment needs to be updated. Behind the scenes, this plugin creates a lockfile at requirements.txt (non-default lockfiles are located at requirements/requirements-{env_name}.txt). Once the dependencies are resolved the plugin will install the lockfile into your virtual environment and keep it up-to-date.

Installation#

Declare hatch-pip-compile as a dependency in your pyproject.toml file under the [tool.hatch.env] table and hatch will automatically install it. You must also have your environment type set to pip-compile (see Configuration).

pyproject.toml

[tool.hatch.env]
requires = [
    "hatch-pip-compile"
]

[tool.hatch.envs.default]
type = "pip-compile"

hatch.toml

[env]
requires = [
    "hatch-pip-compile"
]

[envs.default]
type = "pip-compile"

Configuration#

Set your environment type to pip-compile to use this plugin for the respective environment:

pyproject.toml

[tool.hatch.envs.default]
type = "pip-compile"

hatch.toml
```
[envs.default]
type = "pip-compile"
```

Common Scenarios#

lock-filename - changing the default lockfile path
pip-compile-constraint - syncing dependency versions across environments
Upgrading Dependencies - how to upgrade dependencies
Using Hashes - how to include hashes in your lockfile
Using uv instead of pip-compile - how to use uv instead of pip-compile

Configuration Options#

The plugin gives you options to configure how lockfiles are generated and how they are installed into your environment.

The following example shows how to specify the pip-compile-hashes option on your environment in your pyproject.toml file:

[tool.hatch.envs.default]
type = "pip-compile"
pip-compile-hashes = true

Generating Lockfiles#

name	type	description
lock-filename	`str`	The filename of the ultimate lockfile. `default` env is `requirements.txt`, non-default is `requirements/requirements-{env_name}.txt`
pip-compile-constraint	`str`	An environment to use as a constraint file, ensuring that all shared dependencies are pinned to the same versions.
pip-compile-hashes	`bool`	Whether to generate hashes in the lockfile. Defaults to `false`.
pip-compile-resolver	`str`	Whether to use `pip-compile` or `uv` to resolve dependencies into the project. Defaults to `pip-compile`
pip-compile-args	`list[str]`	Additional command-line arguments to pass to `pip-compile-resolver`
pip-compile-verbose	`bool`	Set to `true` to run `pip-compile` in verbose mode instead of quiet mode, set to `false` to silence warnings

Installing Lockfiles#

name	type	description
pip-compile-installer	`str`	Whether to use `pip`, `pip-sync`, or `uv` to install dependencies into the project. Defaults to `pip`
pip-compile-install-args	`list[str]`	Additional command-line arguments to pass to `pip-compile-installer`