hatch-pip-compile

hatch plugin to use pip-compile 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.

• 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

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

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

Installing Lockfiles

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 to 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 by 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.

NOTE: command line interface

hatch-pip-compile also makes a CLI available to handle the the PIP_COMPILE_UPGRADE / PIP_COMPILE_UPGRADE_PACKAGE workflow automatically. See the hatch-pip-compile CLI section for more information.

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.

Using the hatch-pip-compile CLI

For convenience this package also makes a CLI available to handle the setting / unsetting of the PIP_COMPILE_UPGRADE / PIP_COMPILE_UPGRADE_PACKAGE environment variables and invoking the hatch env run command for you automatically. To use the CLI you'll need to install it outside your pyproject.toml / hatch.toml file.

I recommend using pipx to install the CLI, but you can also install it directly with pip:

pipx install hatch-pip-compile

Once installed, you can run the CLI with the hatch-pip-compile command.

Examples

Upgrade the default environment

The below command will upgrade all packages in the default environment.

hatch-pip-compile --upgrade

Upgrade a non-default environment

The below command will upgrade all packages in the docs environment.

hatch-pip-compile docs --upgrade

Upgrade a specific package

The below command will upgrade the requests package in the default environment.

hatch-pip-compile --upgrade-package requests

Upgrade all pip-compile environments

The below command will upgrade all packages in all pip-compile environments.

hatch-pip-compile --upgrade --all

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

pipx also supports upgrading the plugin when any new versions are released:

pipx runpip hatch install --upgrade hatch-pip-compile

Alternatively, you can install the plugin directly with pip:

pip install hatch hatch-pip-compile

Check Out the Docs

Looking to contribute? See the Contributing Guide

See the Changelog