hatch-pip-compile 1.8.3

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). Once the dependencies are resolved the plugin will install the lockfile into your virtual 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

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

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-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

Installing Lockfiles

name	type	description
pip-compile-installer	str	Whether to use pip or pip-sync 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

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. pip-compile-constraint can also be set to an empty string disable the feature.

• 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 false.

• 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
  

pip-compile-installer

Whether to use pip or pip-sync to install dependencies into the project. Defaults to pip. When you choose the pip option the plugin will run pip install -r {lockfile} under the hood to install the dependencies. When you choose the pip-sync option pip-sync {lockfile} is invoked by the plugin.

The key difference between these options is that pip-sync will uninstall any packages that are not in the lockfile and remove them from your environment. pip-sync is useful if you want to ensure that your environment is exactly the same as the lockfile. If the environment should be used across different Python versions and platforms pip is the safer option to use.

• pyproject.toml

  [tool.hatch.envs.<envName>]
  type = "pip-compile"
  pip-compile-installer = "pip-sync"
  

• hatch.toml

  [envs.<envName>]
  type = "pip-compile"
  pip-compile-installer = "pip-sync"
  

pip-compile-install-args

Extra arguments to pass to pip-compile-installer. For example, if you'd like to use pip as the installer but want to pass the --no-deps flag to pip install you can do so with this option:

• pyproject.toml

  [tool.hatch.envs.<envName>]
  type = "pip-compile"
  pip-compile-installer = "pip"
  pip-compile-install-args = [
      "--no-deps"
  ]
  

• hatch.toml

  [envs.<envName>]
  type = "pip-compile"
  pip-compile-installer = "pip"
  pip-compile-install-args = [
      "--no-deps"
  ]
  

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