This is a tool for managing a recorded version number in setuptools-based python projects. The goal is to remove the tedious and error-prone "update the embedded version string" step from your release process. Making a new release should be as easy as recording a new tag in your version-control system, and maybe making new tarballs.

Quick Install

Versioneer provides two installation modes. The "classic" vendored mode installs a copy of versioneer into your repository. The experimental build-time dependency mode is intended to allow you to skip this step and simplify the process of upgrading.

Vendored mode

• pip install versioneer to somewhere in your $PATH
  • A conda-forge recipe is available, so you can also use conda install -c conda-forge versioneer
• add a [tool.versioneer] section to your pyproject.toml or a [versioneer] section to your setup.cfg (see Install)
  • Note that you will need to add tomli; python_version < "3.11" to your build-time dependencies if you use pyproject.toml
• run versioneer install --vendor in your source tree, commit the results
• verify version information with python setup.py version

Build-time dependency mode

• pip install versioneer to somewhere in your $PATH
  • A conda-forge recipe is available, so you can also use conda install -c conda-forge versioneer
• add a [tool.versioneer] section to your pyproject.toml or a [versioneer] section to your setup.cfg (see Install)
• add versioneer (with [toml] extra, if configuring in pyproject.toml) to the requires key of the build-system table in pyproject.toml:

  [build-system]
  requires = ["setuptools", "versioneer[toml]"]
  build-backend = "setuptools.build_meta"

• run versioneer install --no-vendor in your source tree, commit the results
• verify version information with python setup.py version

Version Identifiers

Source trees come from a variety of places:

• a version-control system checkout (mostly used by developers)
• a nightly tarball, produced by build automation
• a snapshot tarball, produced by a web-based VCS browser, like github's "tarball from tag" feature
• a release tarball, produced by "setup.py sdist", distributed through PyPI

Within each source tree, the version identifier (either a string or a number, this tool is format-agnostic) can come from a variety of places:

• ask the VCS tool itself, e.g. "git describe" (for checkouts), which knows about recent "tags" and an absolute revision-id
• the name of the directory into which the tarball was unpacked
• an expanded VCS keyword (