versioningit
Versioning It with your Version In Git
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.8 or higher; repository must have at least one Git or Mercurial tag for version extraction to work.
- 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 · maintenance · safety
MIT (permissive) — MIT license permits commercial and private use with minimal restrictions; suitable for most projects.
last release 2025-06-27 (413 days) · last repo commit 2026-07-20 · 111 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 2,173,943 downloads/mo, #3,231 on PyPI
Alternatives
Verify before relying
# In pyproject.toml:
[build-system]
requires = ["setuptools", "versioningit"]
build-backend = "setuptools.build_meta"
[tool.versioningit]
# Then build your project; versioningit reads Git tags automatically.- 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.
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 on this page. Verify before relying on it.
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
versioningit on PyPI
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.
Requires Python 3.8 or higher; repository must have at least one Git or Mercurial tag for version extraction to work.
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.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 the current Python release >=3.8 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 3 packagesimportlib-metadatapackagingtomli |
| Maintenance | Actively maintained 413 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 2,173,943 / month, #3,231 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableFramework :: HatchFramework :: Setuptools PluginIntended Audience :: DevelopersProgramming Language :: Python :: 3Programming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.8Programming Language :: Python :: 3.9Programming Language :: Python :: Implementation :: CPythonProgramming Language :: Python :: Implementation :: PyPyTopic :: Software Development :: Build ToolsTopic :: Software Development :: Version ControlTopic :: Software Development :: Version Control :: GitTopic :: Software Development :: Version Control :: MercurialTyping :: Typed |
Evidence: versioningit-3.3.0-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
An agent finds packages by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language. Give your agent the search over MCP.
More Build Tools packages
Provides reusable utilities for Python packaging interoperability, including version handling, specifiers, markers, requirements, tags, and metadata parsing according to standards like PEP 440 and PEP 425.
Wraps any iterable to display a real-time progress bar in the terminal or Jupyter notebook, showing iteration count, elapsed time, and estimated time remaining.
pip is the standard installer for Python packages, enabling you to download and install packages from the Python Package Index and other indexes into your Python environment.
Hatchling is a standards-compliant Python build backend that handles packaging, metadata, and distribution of Python projects when configured in a project's pyproject.toml file.
Generates Python gRPC service stubs and message classes from Protocol Buffer definitions, enabling developers to build gRPC clients and servers.
pre-commit is a framework for installing and running git hooks written in any language before commits are made, automating code quality and validation checks across multi-language projects.
Install it if your team needs consistent, automated validation at commit time.
See also setuptools-git-versioning · hatch-vcs · setuptools-scm · versioneer-518 · versioneer · read-version · uv-dynamic-versioning · charm-refresh-build-version · dunamai · setupmeta