Hatch VCS Plugin

0.5.0 · active · verified Sun Apr 05

Hatch-vcs is a Hatch plugin that enables project versioning using your preferred Version Control System (VCS), such as Git or Mercurial. It integrates with Hatch's build system to dynamically determine the package version based on VCS tags. The current version is 0.5.0, and it maintains an active release cadence, frequently updating to support new Python versions and Hatchling features.

Warnings

breaking Support for Python 3.8 was dropped in version 0.5.0. Projects using older Python versions will need to upgrade Python or pin an older `hatch-vcs` version.
Fix: Upgrade Python to >=3.9 or use `hatch-vcs<0.5.0`. Python 3.7 support was dropped in v0.4.0 and Python 2 in v0.3.0.
gotcha When developing with editable installs, the `_version.py` file generated by `hatch-vcs` is static and won't update automatically during development. The version derived from `importlib.metadata` can also become outdated. For runtime updates, `hatch-vcs` needs to be installed in the runtime environment and an environment variable (`MYPROJECT_HATCH_VCS_RUNTIME_VERSION`) can be set.
Fix: For dynamic version updates in editable installs, a hybrid approach (e.g., falling back to `importlib.metadata` or setting the `MYPROJECT_HATCH_VCS_RUNTIME_VERSION` environment variable and ensuring `hatch-vcs` is available at runtime) is recommended.
gotcha Older versions of `hatch-vcs` (prior to v0.5.0) might emit deprecation warnings when using the `tag-pattern` option due to underlying dependency changes.
Fix: Upgrade to `hatch-vcs` version 0.5.0 or newer to avoid these warnings.
gotcha Before version 0.4.0, a `UserWarning` could be emitted if a template was not explicitly defined when using certain `hatch-vcs` features.
Fix: Upgrade to `hatch-vcs` version 0.4.0 or newer to prevent this warning.

Install

pip install hatch hatch-vcs Install Hatch CLI and plugin
# In pyproject.toml: [build-system] requires = ["hatchling>=1.27", "hatch-vcs>=0.3.0"] build-backend = "hatchling.build" Configure build system

Imports

hatch-vcs
```
No direct Python import. Configured via pyproject.toml.
```
Hatch-vcs is a plugin for Hatch's build system and is configured declaratively in `pyproject.toml`, not imported as a Python module for direct use.

Quickstart

This configuration in `pyproject.toml` sets up `hatch-vcs` to derive your package's version from Git tags. It also specifies a `_version.py` file to be generated at build time, ensuring a static version is available in your distribution. The `project.dynamic` field should include `"version"` to enable dynamic versioning.

# pyproject.toml
[project]
name = "my-package"
version = "0.0.1" # This is a fallback/initial value, will be overridden by VCS
dynamic = ["version"]

[build-system]
requires = ["hatchling>=1.27", "hatch-vcs>=0.3.0"]
build-backend = "hatchling.build"

[tool.hatch.version]
source = "vcs"

[tool.hatch.build.hooks.vcs]
version-file = "src/my_package/_version.py"

# Example of how you might read the version in your package (e.g., in src/my_package/__init__.py)
# from importlib.metadata import version
# try:
#     __version__ = version("my-package")
# except Exception:
#     # Fallback for development installs or if metadata is not yet available
#     __version__ = "0.0.0+unknown"

view raw JSON →