---
id: versioneer
version: "0.29"
license: This is free and unencumbered software released into the public domain. Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# versioneer — Easy VCS-based management of project version strings

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

## 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 above — 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

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

- License: This is free and unencumbered software released into the public domain. Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 4.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

version management from git tags, automatic version string generation, setuptools version automation, vcs-based versioning, release version tracking, python package versioning tool, git tag to version string, version-management, release-automation, git-integration

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