versioneerpy

Versioneerpy is a Python packaging utility designed to automate the derivation of a project's version number from version control metadata. Built to integrate with Python projects, it helps ensure consistent, repeatable version strings across releases by deriving the version from Git tags and history rather than maintaining a manually edited version file.

Core functionality centers on generating or exposing a version reference within the project. Versioneerpy typically produces a small runtime module or exposes a __version__ attribute that reflects the current release string. It uses VCS information, such as git describe output, to create semantic, PEP 440–compliant version numbers. When VCS data is unavailable (for example in a source distribution), it can fall back to a static version value to preserve reproducibility.

Configuration and workflow are designed to be developer-friendly. Projects configure versioneerpy via standard packaging configuration files (such as setup.cfg or pyproject.toml), specifying the location of the generated version file, tag prefixes, and the versioning scheme. The tool provides an initialization step to scaffold the necessary files and can be updated as tagging practices or project requirements evolve.

Usage in a typical development cycle involves installing the tool, running the initialization and configuration steps, and committing changes to the repository. During packaging or distribution, tools that read the project's version will retrieve the derived version automatically, reducing drift between tags, commits, and releases.

Versioneerpy is related to and inspired by similar version-management tools in the Python ecosystem. It is commonly used in open-source projects seeking automated, VCS-derived version strings and streamlined release workflows. See also Versioneer, semantic versioning, and Python packaging.