{"id":3314,"library":"versioningit","title":"Versioning It","description":"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.","status":"active","version":"3.3.0","language":"en","source_language":"en","source_url":"https://github.com/jwodder/versioningit","tags":["versioning","git","mercurial","packaging","setuptools","hatch","pyproject.toml"],"install":[{"cmd":"pip install versioningit","lang":"bash","label":"Install versioningit"},{"cmd":"# In your pyproject.toml (for setuptools)\n[build-system]\nrequires = [\"setuptools\", \"versioningit\"]\nbuild-backend = \"setuptools.build_meta\"\n\n# Or for Hatch\n[build-system]\nrequires = [\"hatchling\", \"versioningit\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.version]\nsource = \"versioningit\"","lang":"toml","label":"Integrate into build system (pyproject.toml)"}],"dependencies":[{"reason":"Runtime dependency for retrieving package version, only for Python < 3.10","package":"importlib-metadata","optional":true},{"reason":"Used for version parsing and comparison.","package":"packaging","optional":false},{"reason":"Used for TOML parsing, only for Python < 3.11","package":"tomli","optional":true}],"imports":[{"note":"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.","wrong":"from versioningit import get_version\n__version__ = get_version()","symbol":"version","correct":"from importlib.metadata import version\n__version__ = version(\"your_package_name\")"},{"note":"Used for advanced library API integration, not for typical pyproject.toml-based setup.","symbol":"Versioningit","correct":"from versioningit import Versioningit"}],"quickstart":{"code":"# pyproject.toml\n[project]\nname = \"my_package\"\nversion = \"dynamic\"\n\n[tool.versioningit]\n# Minimal configuration (uses defaults: Git, basic tag2version, basic format)\n\n# To retrieve the version at runtime (e.g., in my_package/__init__.py):\n# from importlib.metadata import version\n# __version__ = version(\"my_package\")","lang":"toml","description":"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()`."},"warnings":[{"fix":"Consult the changelog for specific breaking changes for each major version upgrade and adjust custom methods/API calls accordingly.","message":"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()`.","severity":"breaking","affected_versions":"3.0.0 and later for API users"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Any explicit 'version' field in `setup.py`, `setup.cfg`, or `pyproject.toml` will be ignored and overwritten by `versioningit`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `dynamic = [\"version\"]` under `[project]` in your `pyproject.toml`.","message":"If using `pyproject.toml` for project metadata (PEP 621), you *must* explicitly declare `version` as dynamic by adding `dynamic = [\"version\"]` to your `[project]` table.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}