Versioneer

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• pip install versioneer Install Versioneer CLI

Imports

• get_versions

  from your_package_name._version import get_versions
  __version__ = get_versions()['version']

  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.
• versioneer.get_version, versioneer.get_cmdclass

  import versioneer
  setup(
      version=versioneer.get_version(),
      cmdclass=versioneer.get_cmdclass(),
      # ... other setup arguments
  )

  This is how Versioneer integrates with setup() in your setup.py file to dynamically set the version and command classes.

Quickstart

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.

import os

# --- After Versioneer setup (via `versioneer install`) --- 
# Assume versioneer has been correctly set up in a project, 
# creating _version.py and modifying __init__.py

# Example of how the version is accessed in your package's __init__.py
# (The `get_versions` function is generated by Versioneer in _version.py)

# Simulate a _version.py and __init__.py setup for demonstration
# In a real project, these files would be managed by Versioneer.

_versioneer_data = {
    'version': os.environ.get('TEST_VERSION', '0.0.1+test.gdeadbeef.dirty'),
    'full-revisionid': 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeef',
    'dirty': True,
    'error': None
}

def get_versions_mock():
    return _versioneer_data

# In your actual package's __init__.py, after `versioneer install`:
# from ._version import get_versions
# __version__ = get_versions()['version']

# For this example, we'll use our mock:
__version__ = get_versions_mock()['version']

print(f"The package version is: {__version__}")

# To see how it changes without a dirty tag:
os.environ['TEST_VERSION'] = '1.2.3'
__version__ = get_versions_mock()['version']
print(f"The package version (clean) is: {__version__}")