{"library":"hatch-vcs","title":"Hatch VCS Plugin","description":"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.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/ofek/hatch-vcs","tags":["hatch","versioning","vcs","git","mercurial","packaging","build-system"],"install":[{"cmd":"pip install hatch hatch-vcs","lang":"bash","label":"Install Hatch CLI and plugin"},{"cmd":"# In pyproject.toml:\n[build-system]\nrequires = [\"hatchling>=1.27\", \"hatch-vcs>=0.3.0\"]\nbuild-backend = \"hatchling.build\"","lang":"toml","label":"Configure build system"}],"dependencies":[{"reason":"Hatch-vcs is a build backend plugin for Hatchling.","package":"hatchling","optional":false},{"reason":"Hatch-vcs utilizes setuptools-scm internally for VCS integration and version derivation.","package":"setuptools-scm","optional":false},{"reason":"Required for Git repository interaction to determine versions. Mercurial is also supported for Mercurial repositories.","package":"git","optional":true}],"imports":[{"note":"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.","symbol":"hatch-vcs","correct":"No direct Python import. Configured via pyproject.toml."}],"quickstart":{"code":"# pyproject.toml\n[project]\nname = \"my-package\"\nversion = \"0.0.1\" # This is a fallback/initial value, will be overridden by VCS\ndynamic = [\"version\"]\n\n[build-system]\nrequires = [\"hatchling>=1.27\", \"hatch-vcs>=0.3.0\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.version]\nsource = \"vcs\"\n\n[tool.hatch.build.hooks.vcs]\nversion-file = \"src/my_package/_version.py\"\n\n# Example of how you might read the version in your package (e.g., in src/my_package/__init__.py)\n# from importlib.metadata import version\n# try:\n#     __version__ = version(\"my-package\")\n# except Exception:\n#     # Fallback for development installs or if metadata is not yet available\n#     __version__ = \"0.0.0+unknown\"\n","lang":"toml","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade to `hatch-vcs` version 0.5.0 or newer to avoid these warnings.","message":"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.","severity":"gotcha","affected_versions":"<0.5.0"},{"fix":"Upgrade to `hatch-vcs` version 0.4.0 or newer to prevent this warning.","message":"Before version 0.4.0, a `UserWarning` could be emitted if a template was not explicitly defined when using certain `hatch-vcs` features.","severity":"gotcha","affected_versions":"<0.4.0"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}