hatch-vcs

library0.5.0pypypiunverified

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.

devops

pip install hatch hatch-vcs

github ↗package ↗changelog ↗

Install & Compatibility

Where this runs

tested against v0.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

4/6 runs

py 3.11

4/6 runs

py 3.12

4/6 runs

py 3.13

4/6 runs

py 3.9

4/6 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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"

hatch --version

Debug

Known issues

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

affects: >=0.5.0

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

affects: All

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

affects: <0.5.0

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

affects: <0.4.0

breakingAttempting 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`).

affects: All

breakingA `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.

affects: All

Upgrade

Version history

0.5.0latest on PyPI

Audit

Dependencies

hatchlingrequiredHatch-vcs is a build backend plugin for Hatchling.

setuptools-scmrequiredHatch-vcs utilizes setuptools-scm internally for VCS integration and version derivation.

gitoptionalRequired for Git repository interaction to determine versions. Mercurial is also supported for Mercurial repositories.

Agent activity

88 hits · last 30 days

node

seranking-bot

ahrefsbot

bytedance

chatgpt-user

Amazon

Resources

githubhttps://github.com/sponsors/ofek ↗

packagehttps://pypi.org/project/hatch-vcs/ ↗

changeloghttps://github.com/ofek/hatch-vcs/blob/master/HISTORY.md ↗