versioneer

What it is and what it does

Versioneer is a build-time tool that automatically manages version strings in Python projects by querying your version-control system instead of requiring manual edits. It installs files into your project that dynamically compute version information from git tags and commit metadata at import time, and handles version computation during setup and distribution.

The tool supports two installation modes: vendored (copies versioneer into your repo) and build-time dependency (declares versioneer as a build requirement). It generates version strings in PEP 440 format by default, including tag name for releases and additional metadata (commit distance, commit hash, dirty state) for development builds. This eliminates the error-prone step of manually updating version strings before each release—you only need to tag your repository.

Use it for:

• Automatically derive a package's version from the latest git tag without manual edits
• Generate version strings for sdist tarballs that reflect the exact commit they were built from
• Provide developers with version info that includes commit hash and dirty state for debugging
• Simplify release workflows by removing the 'update version string' step from your checklist
• Support multiple version-string styles via configuration

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Versioneer automates version management in setuptools-based Python projects by deriving version strings from version-control tags at build and runtime, eliminating manual version-string updates.

Yes. Versioneer is actively maintained, has no runtime dependencies, and solves a genuine release-process pain point. Use it if you manage a setuptools-based project with git tags and want to eliminate manual version-string updates. The vendored mode is stable; the build-time dependency mode is marked experimental, so prefer vendored for production projects unless you have a specific reason to avoid vendoring.

Install

versioneer on PyPI

pip install versioneer

uv add versioneer

poetry add versioneer

Installing versioneer

Before you install

Low friction: pure Python wheel with no runtime dependencies. Actively maintained with recent commits; last release was 2023-07-07 but repo shows ongoing activity as of 2026-06-01.

License in practice

Released into the public domain under the Unlicense (permissive). No restrictions on use, modification, or distribution for any purpose, commercial or otherwise.

Quickstart

pip install versioneer
versioneer install --vendor
# In your project's __init__.py:
from ._version import get_versions
__version__ = get_versions()['version']

Requires a git repository and setuptools-based project structure; versioneer must be run in your source tree and results committed.

Verify before relying

• Whether the build-time dependency mode is production-ready or still experimental
• Performance impact of dynamic version lookup at import time in large projects
• Compatibility with non-setuptools build systems (e.g., hatch, flit, poetry)

Package facts

Evidence: versioneer-0.29-py3-none-any.whl

Tags

More Build Tools packages