{"id":2351,"library":"versioneer","title":"Versioneer","description":"Versioneer is a Python tool that provides easy, VCS-based management of project version strings for setuptools-based projects. It aims to automate the process of updating version numbers, making releases as simple as creating a new VCS tag. It is actively maintained with regular releases, currently at version 0.29.","status":"active","version":"0.29","language":"en","source_language":"en","source_url":"https://github.com/python-versioneer/python-versioneer","tags":["versioning","VCS","git","setuptools","packaging","build-system","automation"],"install":[{"cmd":"pip install versioneer","lang":"bash","label":"Install Versioneer CLI"}],"dependencies":[{"reason":"Required for integration with setuptools-based projects, which is Versioneer's primary use case.","package":"setuptools","optional":false},{"reason":"Required for parsing pyproject.toml on Python versions older than 3.11, when using the [toml] extra. Python 3.11+ uses the built-in tomllib.","package":"tomli","optional":true}],"imports":[{"note":"This pattern is typically used in your package's __init__.py after Versioneer has been installed into your project. Versioneer generates the _version.py file.","symbol":"get_versions","correct":"from your_package_name._version import get_versions\n__version__ = get_versions()['version']"},{"note":"This is how Versioneer integrates with setup() in your setup.py file to dynamically set the version and command classes.","wrong":"setup(version='X.Y.Z', ...)","symbol":"versioneer.get_version, versioneer.get_cmdclass","correct":"import versioneer\nsetup(\n    version=versioneer.get_version(),\n    cmdclass=versioneer.get_cmdclass(),\n    # ... other setup arguments\n)"}],"quickstart":{"code":"import os\n\n# --- After Versioneer setup (via `versioneer install`) --- \n# Assume versioneer has been correctly set up in a project, \n# creating _version.py and modifying __init__.py\n\n# Example of how the version is accessed in your package's __init__.py\n# (The `get_versions` function is generated by Versioneer in _version.py)\n\n# Simulate a _version.py and __init__.py setup for demonstration\n# In a real project, these files would be managed by Versioneer.\n\n_versioneer_data = {\n    'version': os.environ.get('TEST_VERSION', '0.0.1+test.gdeadbeef.dirty'),\n    'full-revisionid': 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeef',\n    'dirty': True,\n    'error': None\n}\n\ndef get_versions_mock():\n    return _versioneer_data\n\n# In your actual package's __init__.py, after `versioneer install`:\n# from ._version import get_versions\n# __version__ = get_versions()['version']\n\n# For this example, we'll use our mock:\n__version__ = get_versions_mock()['version']\n\nprint(f\"The package version is: {__version__}\")\n\n# To see how it changes without a dirty tag:\nos.environ['TEST_VERSION'] = '1.2.3'\n__version__ = get_versions_mock()['version']\nprint(f\"The package version (clean) is: {__version__}\")","lang":"python","description":"Versioneer itself is a tool to *manage* your project's version, not a library meant for direct runtime consumption in most application code beyond obtaining the `__version__` string. The primary use involves running `versioneer install` in your project's root, configuring `setup.cfg` or `pyproject.toml`, and then modifying `setup.py` (if applicable). This setup creates a `_version.py` file in your package (e.g., `src/your_package/_version.py`) which defines `get_versions()`. Your `__init__.py` then typically imports and uses this to set `__version__`. The code snippet demonstrates how the version string would be retrieved in a Python module after Versioneer has been set up."},"warnings":[{"fix":"Upgrade to Python 3.7+ and ensure `setuptools` is up-to-date. Review release notes for specific `distutils` related changes if you have a custom build process.","message":"Versioneer dropped official support for Python 3.6 in version 0.23, and removed old `distutils` hacks. Users on Python 3.6 or older `setuptools`/`distutils` versions may encounter issues or compilation failures.","severity":"breaking","affected_versions":"<0.23"},{"fix":"Run `python setup.py version` in your project root for verbose debugging output which includes the error string. Ensure your `.git` directory is present and accessible, and that `versioneer install` was run successfully. For subprojects, `pip install --editable .` might be necessary.","message":"Versioneer defaults to `0+unknown` if it cannot correctly determine the version string from your VCS (e.g., Git) or if there are problems during its lookup. This can happen with `pip install .` from subproject directories or misconfigured VCS repositories.","severity":"gotcha","affected_versions":"All"},{"fix":"Carefully configure `versionfile_source` and `versionfile_build` in your `setup.cfg` or `pyproject.toml` to accurately reflect your project structure. Consider using `pip install --editable .` for development installs in subdirectories.","message":"Versioneer has limited support for source trees where `setup.py` (or `pyproject.toml` in newer versions) is not in the root directory alongside your VCS (`.git`) directory, especially in multi-subproject layouts.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade to Versioneer 0.29 or newer for improved `pyproject.toml`-only build system support. Ensure your `pyproject.toml` includes `versioneer[toml]` in `build-system.requires` and a `[tool.versioneer]` section.","message":"When configuring Versioneer via `pyproject.toml` in 'build-time dependency mode' (using `--no-vendor`), older versions of Versioneer may incorrectly complain about a missing `setup.py`. While version 0.29 improved support for `pyproject.toml`-only projects, older versions expected `setup.py` to be present.","severity":"breaking","affected_versions":"<0.29"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}