Versioning It

3.3.0 · active · verified Sat Apr 11

Versioningit is a Python packaging plugin that automatically determines your package's version based on tags in your version control repository (Git and Mercurial supported). It offers extensive customization for version formatting and allows overriding internal functions for version extraction and calculation. It integrates with both setuptools and Hatch. The current version is 3.3.0, and it has a regular release cadence with several updates throughout the year.

Warnings

breaking Major versions of versioningit (e.g., v3.0.0) may introduce breaking changes, primarily to the library and custom method API. For example, v3.0.0 changed the `build_dir` argument for `Versioningit.do_onbuild()` and renamed the `version` argument to `base_version` in `Versioningit.do_format()`.
Fix: Consult the changelog for specific breaking changes for each major version upgrade and adjust custom methods/API calls accordingly.
gotcha Versioningit requires the entire repository history (or at least back to the most recent tag) to determine the version. Building or installing from shallow clones (common in CI environments) will not work correctly.
Fix: Ensure your CI/CD pipeline performs a full clone of the repository (e.g., `git fetch --unshallow` or configure your CI system not to use shallow clones).
gotcha Any explicit 'version' field in `setup.py`, `setup.cfg`, or `pyproject.toml` will be ignored and overwritten by `versioningit`.
Fix: Remove any explicit 'version' declarations from your project metadata files to prevent confusion and ensure `versioningit` is the single source of truth for your package version.
gotcha If using `pyproject.toml` for project metadata (PEP 621), you *must* explicitly declare `version` as dynamic by adding `dynamic = ["version"]` to your `[project]` table.
Fix: Add `dynamic = ["version"]` under `[project]` in your `pyproject.toml`.
gotcha During editable installs (`pip install -e .`), the version calculated by `versioningit` is only updated when the install command is re-run. Changes to VCS tags or repository state after the initial editable install will not be reflected until re-installation.
Fix: Re-run `pip install -e .` after making changes that should update the version if you need the runtime version to be current during development.
gotcha If you define and use custom methods within your Python package, retrieving the package version using `importlib.metadata.version()` inside `__init__.py` might fail during the build process, as `versioningit` loads the package before it's fully installed.
Fix: Wrap `importlib.metadata.version()` calls in `__init__.py` with a `try...except` block, or consider using the `[tool.versioningit.write]` configuration to write the version to a file that can be safely imported at runtime.
gotcha If `[tool.versioningit].default-version` is not set in `pyproject.toml` and an error occurs during version calculation (e.g., no tags found in repository), the build or install process will fail.
Fix: Add a `default-version` setting (e.g., `default-version = "0.0.0+unknown"`) under `[tool.versioningit]` in your `pyproject.toml` to provide a fallback version in case of errors.

Install

pip install versioningit Install versioningit
# In your pyproject.toml (for setuptools) [build-system] requires = ["setuptools", "versioningit"] build-backend = "setuptools.build_meta" # Or for Hatch [build-system] requires = ["hatchling", "versioningit"] build-backend = "hatchling.build" [tool.hatch.version] source = "versioningit" Integrate into build system (pyproject.toml)

Imports

version
```
from importlib.metadata import version
__version__ = version("your_package_name")
```
For runtime version retrieval, `importlib.metadata.version` is the recommended Python standard. Direct use of `versioningit.get_version()` is primarily for library API integration, not common package runtime use.
Versioningit
```
from versioningit import Versioningit
```
Used for advanced library API integration, not for typical pyproject.toml-based setup.

Quickstart

Configure `versioningit` in your `pyproject.toml` file by adding a `[tool.versioningit]` table. Ensure `project.version = "dynamic"` and `project.dynamic = ["version"]` are set in your `[project]` table. For runtime access to the version, use `importlib.metadata.version()`.

# pyproject.toml
[project]
name = "my_package"
version = "dynamic"

[tool.versioningit]
# Minimal configuration (uses defaults: Git, basic tag2version, basic format)

# To retrieve the version at runtime (e.g., in my_package/__init__.py):
# from importlib.metadata import version
# __version__ = version("my_package")

view raw JSON →