Install & Compatibility
Where this runs
tested against v3.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.214s · 19.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.192s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Versioningit
✓ from versioningit import Versioningit
✗ from importlib.metadata import version
config
✓ from versioningit import config
errors
✓ from versioningit import errors
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")
versioningit --version
Debug
Known issues
breakingMajor 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()`.fixConsult the changelog for specific breaking changes for each major version upgrade and adjust custom methods/API calls accordingly.
affects: 3.0.0 and later for API users
gotchaVersioningit 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.fixEnsure 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).
affects: All versions
gotchaAny explicit 'version' field in `setup.py`, `setup.cfg`, or `pyproject.toml` will be ignored and overwritten by `versioningit`.fixRemove 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.
affects: All versions
gotchaIf using `pyproject.toml` for project metadata (PEP 621), you *must* explicitly declare `version` as dynamic by adding `dynamic = ["version"]` to your `[project]` table.fixAdd `dynamic = ["version"]` under `[project]` in your `pyproject.toml`.
affects: All versions
gotchaDuring 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.fixRe-run `pip install -e .` after making changes that should update the version if you need the runtime version to be current during development.
affects: All versions
gotchaIf 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.fixWrap `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.
affects: All versions
gotchaIf `[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.fixAdd 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.
affects: All versions
Upgrade
Version history
3.3.0latest on PyPI · released Jun 27, 2025
Audit
Dependencies
importlib-metadataoptionalRuntime dependency for retrieving package version, only for Python < 3.10
packagingrequiredUsed for version parsing and comparison.
tomlioptionalUsed for TOML parsing, only for Python < 3.11