Hatch Pip Compile

1.11.6 verified Fri May 01 auth: no python

A Hatch plugin that uses pip-compile (from pip-tools) to manage project dependencies, generating lockfiles and resolving versions. Current version 1.11.6, updated January 2026. Active development with regular bug fixes.

pip install hatch-pip-compile

Common errors

error KeyError: 'HATCH_PIP_COMPILE_LOCKFILE' ↓

cause The plugin expects the environment variable to be set but it is missing.

fix

Set the environment variable or remove the override from configuration.

error ModuleNotFoundError: No module named 'hatch_pip_compile' ↓

cause The package is not installed or the import path is wrong.

fix

Install the package: 'pip install hatch-pip-compile'. Then import correctly: 'from hatch_pip_compile.plugin import HatchPipCompileBase'.

error pip-compile: command not found ↓

cause pip-tools is not installed in the environment where Hatch runs.

fix

Install pip-tools: 'pip install pip-tools' or ensure your base Python has it.

Warnings

gotcha The lockfile is generated using pip-compile but the environment installation uses pip, not uv by default. To use uv, set installer = "uv" in [tool.hatch.envs.default]. ↓

fix Add 'installer = "uv"' to [tool.hatch.envs.default] in pyproject.toml if you want uv-based resolution.

breaking In v1.11.0, the plugin migrated to HatchPipCompileBase. If you imported or subclassed the old plugin class, your code may break. ↓

fix Use 'from hatch_pip_compile.plugin import HatchPipCompileBase' instead of the previous class.

gotcha The plugin reads environment variables like HATCH_PIP_COMPILE_LOCKFILE to override lockfile path, but the variable name case matters. Common mistake: using HATCH_PIP_COMPILE_LOCKFILE instead of the correct HATCH_PIP_COMPILE_LOCKFILE. ↓

fix Ensure environment variable is exactly HATCH_PIP_COMPILE_LOCKFILE (all caps) to override lockfile path.

Imports

HatchPipCompileBase

wrong

from hatch_pip_compile import HatchPipCompileBase

correct

from hatch_pip_compile.plugin import HatchPipCompileBase

Wrong top-level import; HatchPipCompileBase is in plugin module

Quickstart

Enable pip-compile lockfile management for Hatch environments by adding configuration to pyproject.toml.

# Add to pyproject.toml under [tool.hatch.envs.default]
# pip-compile = true
# lockfile = "requirements.lock"

# Then run:
# hatch env create