Hatch VCS Plugin

0.5.0 · active · verified Sat Apr 11

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.

Common errors

```
LookupError: setuptools-scm was unable to detect version
```
cause This error occurs when `hatch-vcs` (which uses `setuptools-scm` internally) cannot find sufficient version control system metadata, such as a `.git` directory, accessible Git tags, or when building from an incomplete source like a GitHub tarball without VCS history.

fix Ensure your project is a fully intact Git repository (or other configured VCS) with at least one tag. If building from a tarball, ensure it includes VCS metadata or use `fallback-version` in your `pyproject.toml` to provide a default version if tags are not found. For monorepos or non-standard layouts, you might need to configure `raw-options = { search_parent_directories = true }` or `root = "../.."` under `[tool.hatch.version]` to help `setuptools-scm` locate the VCS root.
```
ModuleNotFoundError: No module named '..._version'
```
cause This typically happens when you are using the `_version.py` build hook feature of `hatch-vcs` and try to run your project directly from source without first installing it, as the `_version.py` file is generated during the install or build process.

fix Install your package, preferably in editable mode during development, to ensure the `_version.py` file is generated: `pip install --editable .` or `hatch env create` if using Hatch environments.
```
Unknown version source: vcs
```
cause This error indicates that `hatch-vcs` is specified as the version source in your `pyproject.toml` (e.g., `source = "vcs"`) but the `hatch-vcs` plugin itself is not installed in the environment where Hatch is trying to determine the version. It can also occur if a runtime version environment variable is set without `hatch-vcs` being available.

fix Ensure `hatch-vcs` is listed as a build dependency in your `pyproject.toml` under `[build-system] requires = ["hatchling", "hatch-vcs"]`. Also, make sure it is installed in your development environment if you are testing locally: `pip install hatch-vcs`.
```
Error getting the version from source vcs: no such group
```
cause This error occurs when the `tag-pattern` configuration in your `pyproject.toml` for `hatch-vcs` is incorrect. The regular expression pattern used to extract the version from Git tags either doesn't match any tag or doesn't contain a named capturing group (e.g., `(?P<version>...)`) or a single unnamed capturing group for the version part.

fix Adjust the `tag-pattern` in your `pyproject.toml` or `hatch.toml` under `[tool.hatch.version]` to correctly match your Git tags and capture the version. For example, if your tags are like `v1.2.3`, a pattern like `v(?P<version>\d+\.\d+\.\d+)` would work.

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.
breaking Attempting to execute a Python script that contains TOML configuration syntax (e.g., `build-backend = "hatchling.build"`) will result in a `SyntaxError`. This error is due to invalid Python code and the interpreter attempting to parse non-Python syntax, not a specific `hatch-vcs` issue.
Fix: Ensure Python scripts are syntactically valid and contain only Python code. Do not embed or directly execute configuration file syntax (like TOML) within Python scripts. If reading configuration, use appropriate libraries (e.g., `tomllib` or `toml`).
breaking A `SyntaxError` on the `build-backend` line (e.g., `build-backend = "hatchling.build"`) indicates a fundamental issue with the project's `pyproject.toml` file or the way it's being processed. This typically happens when `pyproject.toml` content is mistakenly executed as Python code, preventing the build system (and thus `hatch-vcs`) from being initialized.
Fix: Ensure that your `pyproject.toml` file is correctly structured under the `[build-system]` table and is being parsed by a compatible build tool (like `pip` or `hatch`) and not directly executed as Python code within a script or an incompatible environment.

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 →