---
id: versioningit
version: "3.3.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# versioningit — Versioning It with your Version In Git

License: permissive · Maintenance: active · Downloads: 2.2M/mo

## What it is and what it does

versioningit is a build-system plugin that derives your package version from version control tags instead of requiring you to maintain an explicit version string in setup.py, setup.cfg, or pyproject.toml. It works as a setuptools or Hatch plugin, configured via pyproject.toml or versioningit.toml, and supports Git, Git archives, and Mercurial repositories. The plugin queries your VCS for the latest tag, calculates the version based on distance from that tag and repository state (clean, dirty, or both), and formats the result using customizable template strings.

The package's main strength is its flexibility: you can define separate format templates for different repository states (e.g., "1.2.3.post42+ge174a1f" when ahead of a tag, "1.2.3+d20230922" when uncommitted changes exist), and you can override the individual functions that extract tags, calculate versions, bump versions, and write output. It can optionally write the computed version to a file for runtime inspection or inject it into source code at build time. All three runtime dependencies are standard and lightweight.

Use it for:

- Eliminate manual version bumping in setup.py or pyproject.toml by deriving version automatically from Git tags during build.
- Customize version format via template strings without code changes to match your project's versioning scheme.
- Write computed version to a file or inject it into source code at build time for runtime access without re-querying VCS.
- Use custom version calculation logic by defining or registering entry-point functions for tag parsing, version bumping, and formatting.
- Support non-Python projects via versioningit.toml or projects using setuptools, Hatch, or library-mode setup.py integration.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Automatically determines your Python package's version from Git or Mercurial tags and writes it to your build system, with customizable version formatting and optional runtime file generation.

Yes. versioningit is actively maintained, has no known vulnerabilities, installs with low friction, and solves a real problem for projects that want version-from-VCS automation without manual version strings. It is particularly valuable if you need flexible version formatting or custom version logic. The MIT license imposes no restrictions. Install it in your build-system.requires if you use setuptools or Hatch and have Git tags.

## Install

pip install versioningit
uv add versioningit
poetry add versioningit

## Installing versioningit

Before you install: Low friction: pure Python wheel with only three lightweight runtime dependencies (importlib-metadata, packaging, tomli). Active maintenance with recent commits; last release 413 days ago but repository shows ongoing activity.

License in practice: MIT license permits commercial and private use with minimal restrictions; suitable for most projects.

Quickstart:

# In pyproject.toml:
[build-system]
requires = ["setuptools", "versioningit"]
build-backend = "setuptools.build_meta"

[tool.versioningit]

# Then build your project; versioningit reads Git tags automatically.

Requires Python 3.8 or higher; repository must have at least one Git or Mercurial tag for version extraction to work.

Verify before relying:

- Whether custom hooks and entry points for version calculation are well-documented and stable across versions.
- Performance characteristics when used with very large Git histories or many tags.
- Specific PEP compliance details for generated version strings across different format configurations.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

automatic version from git tags, setuptools version plugin, hatch version source, git-based package versioning, dynamic version from vcs, version control versioning, build-time version injection, build-automation, version-management, vcs-integration

[View on SkillFed](https://skillfed.io/packages/versioningit) · [View on PyPI](https://pypi.org/project/versioningit/)