versioneer

library0.29pypiunverified

Versioneer automates version string generation for Python packages based on their Git, Mercurial, or SVN tags. It works by embedding version-calculating code directly into your project's source tree, making your package self-sufficient for versioning even in sdist archives. It currently supports Python 3.7+ and is at version 0.29, with active development and releases tied to new Python versions and build system changes.

devops

pip install versioneer

INSTALL

IMPORT

SIG · VERSIONEER

versioneer

devopsenv0.29

Install

1.5s avg

Import

81ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.29 · 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

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.086s · 18MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 1.5s · import 0.075s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

versioneer

✓ import versioneer

Imported in setup.py (or internally by build backends) to obtain version string and command classes.

get_versions

✓ from ._version import get_versions

Commonly used in your package's __init__.py to expose the runtime version string, after Versioneer has generated the _version.py file.

This quickstart outlines the steps to integrate Versioneer into a new or existing Python project. It involves installing the Versioneer command-line tool, initializing it within your project (which generates `versioneer.py` and `_version.py`), configuring `pyproject.toml` for modern build systems, and optionally exposing the version via your package's `__init__.py`. Finally, commit the changes and tag a release in your version control system for Versioneer to detect the initial version.

# 1. Install the Versioneer CLI tool (if not already installed globally or in venv) pip install versioneer # 2. Navigate to your project root (which must be a Git/Mercurial/SVN repo) cd my_project_root # 3. Initialize Versioneer in your project versioneer install # 4. Configure pyproject.toml (my_project_root/pyproject.toml) # [build-system] # requires = ["setuptools>=61.0.0", "wheel", "versioneer[toml]>=0.28"] # build-backend = "setuptools.build_meta" # [project] # name = "my-awesome-package" # dynamic = ["version"] # # ... other project metadata # [tool.versioneer] # VCS = "git" # style = "pep440" # versionfile_source = "src/my_awesome_package/_version.py" # versionfile_build = "my_awesome_package/_version.py" # tag_prefix = "v" # parentdir_prefix = "my-awesome-package-" # 5. Integrate version into your package's __init__.py (my_project_root/src/my_awesome_package/__init__.py) # from ._version import get_versions # __version__ = get_versions()['version'] # del get_versions # 6. Commit the generated files (versioneer.py, _version.py) and new configurations git add . git commit -m "Add Versioneer for versioning" # 7. Tag a release for Versioneer to detect the version git tag v1.0.0 # Your project will now automatically derive its version from Git tags during builds.

versioneer --version

Debug

Known issues

breakingVersioneer dropped support for Python 3.6 and older versions, alongside removing deprecated `distutils` integration. Projects requiring older Python versions or relying on `distutils` will need to remain on Versioneer versions prior to 0.23.

fix

Upgrade to Python 3.7+ and ensure your build system uses `setuptools` instead of `distutils`. If stuck on older Python, pin `versioneer<0.23`.

affects: <=0.22

gotchaThe `pip install versioneer` command only installs the CLI tool. To integrate versioning into your project, you must run `versioneer install` within your project root. Forgetting this step or not committing the generated `versioneer.py` and `_version.py` files will prevent your project from being versioned correctly.

fix

Always run `versioneer install` in your project's root directory and commit the generated `versioneer.py` and `_version.py` files to your version control system.

affects: All

gotchaVersioneer relies on a clean SCM working directory and properly formatted tags (e.g., `v1.2.3`) to determine versions. Untagged commits or modified files in the working directory can result in 'dirty' or 'unknown' version strings, which might not be desirable for releases.

fix

Ensure all changes are committed and your latest release is tagged. Use `git status` to verify a clean working tree before building release artifacts. Follow the recommended tag prefix (e.g., `v`) configured in `tool.versioneer.tag_prefix`.

affects: All

breakingThe license for Versioneer changed from MIT to Unlicense (effectively public domain) starting with version 0.24. Users should be aware of this change for legal and compliance reasons.

fix

Review the Unlicense terms and ensure it aligns with your project's licensing requirements. No code changes are required for this license update.

affects: >=0.24

gotchaIncorrect or incomplete configuration in `pyproject.toml` (e.g., missing `build-system.requires` for Versioneer, or misconfigured `tool.versioneer` paths) can lead to build failures or incorrect version detection, especially with modern `setuptools` dynamic versioning.

fix

Carefully follow the `pyproject.toml` configuration examples in the official documentation, ensuring `build-system.requires` includes `versioneer[toml]`, `project.dynamic = ['version']`, and `tool.versioneer` paths like `versionfile_source` and `versionfile_build` match your project structure.

affects: >=0.28

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'versioneer'

The `versioneer.py` and `_version.py` files were not generated by `versioneer install` or were not committed/included in the build context.

fix

Run `versioneer install` in your project root, then ensure `versioneer.py` and `_version.py` are present and committed. If using `setup.py`, ensure `versioneer.py` is in the same directory or accessible on the Python path.

AttributeError: module 'versioneer' has no attribute 'get_version'

This usually indicates an older or incomplete `versioneer.py` file, or a misconfigured import/usage. It can also happen if `versioneer install` was run but generated an outdated or corrupted file.

fix

Ensure `versioneer install` has been run recently to get the latest `versioneer.py` and `_version.py`. Verify that your `setup.py` (if used) correctly calls `versioneer.get_version()` and `versioneer.get_cmdclass()`.

Command 'git' failed with exit code 128 (usually indicates a non-git repo)

Versioneer attempts to read version information from your project's Git (or other VCS) repository. This error occurs if the project is not a valid Git repository, or Git is not installed/accessible.

fix

Initialize your project as a Git repository (`git init`), make an initial commit, and tag at least one release (`git tag v0.1.0`). Ensure Git is installed and in your system's PATH.

ERROR: 'pyproject.toml' is malformed

The `pyproject.toml` file contains syntax errors, invalid TOML, or is missing required sections/keys for Versioneer's configuration.

fix

Carefully review your `pyproject.toml` against the official Versioneer documentation for correct syntax and required `build-system` and `tool.versioneer` sections. Use a TOML linter to check for syntax errors.

KeyError: 'version' when calling get_versions()

This happens when `_version.py` is imported but `get_versions()` fails to retrieve a 'version' key, often due to an inability to determine the version from the SCM, or the generated `_version.py` is outdated/corrupted.

fix

Ensure `versioneer install` was run and `_version.py` contains valid version-determining logic. Check if your SCM repository is clean and has tags for Versioneer to use. You might also want to add fallback logic for `__version__` in `__init__.py` for robustness.

Upgrade

Version history

0.29latest on PyPI · released Jul 7, 2023

Audit

Dependencies

setuptoolsrequiredRequired for integration with Python's build system, especially for dynamic versioning.

wheelrequiredCommonly used alongside setuptools for building binary wheels.

tomlrequiredFor parsing pyproject.toml configurations on Python versions prior to 3.11. On 3.11+, tomllib is used.

Agent activity

4 hits · last 30 days

node

Resources

No resource links recorded.