hatch-pip-compile 1.5.0

hatch plugin to use pip-compile to manage project dependencies

hatch-pip-compile

hatch plugin to use pip-compile to manage project dependencies and lockfiles.

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"
  

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). Alongside pip-compile, this plugin also uses pip-sync to install the dependencies from the lockfile into your environment.

• lock-filename - changing the default lockfile path
• pip-compile-constraint - syncing dependency versions across environments
• Upgrading Dependencies - how to upgrade dependencies

Configuration

The environment plugin name is pip-compile. 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"
  

Configuration Options

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 true.
pip-compile-verbose	bool	Set to true to run pip-compile in verbose mode instead of quiet mode, set to false to silence warnings
pip-compile-args	list[str]	Additional command-line arguments to pass to pip-compile

Examples

lock-filename

The path (including the directory) to the ultimate lockfile. Defaults to requirements.txt in the project root for the default environment, and requirements/requirements-{env_name}.txt for non-default environments.

Changing the lock file path:

• pyproject.toml

  [tool.hatch.envs.<envName>]
  type = "pip-compile"
  lock-filename = "locks/{env_name}.lock"
  

• hatch.toml

  [envs.<envName>]
  type = "pip-compile"
  lock-filename = "locks/{env_name}.lock"
  

Changing the lock filename to a path in the project root:

• pyproject.toml

  [tool.hatch.envs.lint]
  type = "pip-compile"
  lock-filename = "linting-requirements.txt"
  

• hatch.toml

  [envs.lint]
  type = "pip-compile"
  lock-filename = "linting-requirements.txt"
  

pip-compile-constraint

An environment to use as a constraint, ensuring that all shared dependencies are pinned to the same versions. For example, if you have a default environment and a test environment, you can set the pip-compile-constraint option to default on the test environment to ensure that all shared dependencies are pinned to the same versions.

• pyproject.toml

  [tool.hatch.envs.default]
  type = "pip-compile"
  
  [tool.hatch.envs.test]
  dependencies = [
      "pytest"
  ]
  type = "pip-compile"
  pip-compile-constraint = "default"
  

• hatch.toml

  [envs.default]
  type = "pip-compile"
  
  [envs.test]
  dependencies = [
      "pytest"
  ]
  type = "pip-compile"
  pip-compile-constraint = "default"
  

By default, all environments inherit from the default environment via inheritance. A common use case is to set the pip-compile-constraint and type options on the default environment and inherit them on all other environments. It's important to note that when detached = true, inheritance is disabled and the type and pip-compile-constraint options must be set explicitly.

• pyproject.toml

  [tool.hatch.envs.default]
  type = "pip-compile"
  pip-compile-constraint = "default"
  
  [tool.hatch.envs.test]
  dependencies = [
      "pytest"
  ]
  

• hatch.toml

  [envs.default]
  type = "pip-compile"
  pip-compile-constraint = "default"
  
  [envs.test]
  dependencies = [
      "pytest"
  ]
  

pip-compile-hashes

Whether to generate hashes in the lockfile. Defaults to true.

• pyproject.toml

  [tool.hatch.envs.<envName>]
  type = "pip-compile"
  pip-compile-hashes = true
  

• hatch.toml

  [envs.<envName>]
  type = "pip-compile"
  pip-compile-hashes = true
  

pip-compile-args

Extra arguments to pass to pip-compile. Custom PyPI indexes can be specified here.

• pyproject.toml

  [tool.hatch.envs.<envName>]
  type = "pip-compile"
  pip-compile-args = [
      "--index-url",
      "https://pypi.org/simple",
  ]
  

• hatch.toml

  [envs.<envName>]
  type = "pip-compile"
  pip-compile-args = [
      "--index-url",
      "https://pypi.org/simple",
  ]
  

pip-compile-verbose

Set to true to run pip-compile in verbose mode instead of quiet mode.

Optionally, if you would like to silence any warnings set the pip-compile-verbose option to false.

• pyproject.toml

  [tool.hatch.envs.<envName>]
  type = "pip-compile"
  pip-compile-verbose = true
  

• hatch.toml

  [envs.<envName>]
  type = "pip-compile"
  pip-compile-verbose = true
  

Upgrading Dependencies

Upgrading all dependencies can be as simple as deleting your lockfile and recreating it by reactivating the environment:

rm requirements.txt
hatch env run --env default -- python --version

If you're a user of the --upgrade / --upgrade-package options on pip-compile, these features can be enabled on this plugin using the environment variables PIP_COMPILE_UPGRADE and PIP_COMPILE_UPGRADE_PACKAGE. When either of these environment variables are set hatch will force the lockfile to be regenerated whenever the environment is activated.

To run with upgrade functionality on the default environment:

PIP_COMPILE_UPGRADE=1 hatch env run --env default -- python --version

To run with upgrade-package functionality on the docs environment:

PIP_COMPILE_UPGRADE_PACKAGE="mkdocs,mkdocs-material" hatch env run --env docs -- python --version

The above commands call python --version on a particular environment, but the same behavior applies to any script that activates the environment.

Notes

Dev Dependencies

Using the default hatch configuration, dev dependencies listed in your default environment (like pytest) will be included on the default lockfile (requirements.txt). If you want to remove your dev dependencies from the lockfile you must remove them from the default environment on your pyproject.toml / hatch.toml file.

Disabling Changes to the Lockfile

In some scenarios, like in CI/CD, you may want to prevent the plugin from making changes to the lockfile. If you set the PIP_COMPILE_DISABLE environment variable to any non-empty value, the plugin will raise an error if it detects that the lockfile needs to be updated.

PIP_COMPILE_DISABLE=1 hatch env run python --version

Manual Installation

If you want to manually install this plugin instead of adding it to the [tool.hatch.env] table, you can do so with pipx:

pipx install hatch
pipx inject hatch hatch-pip-compile

Alternatively, you can install it with pip:

pip install hatch hatch-pip-compile

---

---

Check Out the Docs

Looking to contribute? See the Contributing Guide

See the Changelog