# versioneer

> Easy VCS-based management of project version strings

- **URL**: https://www.freshcrate.ai/projects/versioneer
- **Author**: Brian Warner
- **Category**: Developer Tools
- **Latest version**: `0.29` (2026-04-21)
- **License**: non-standard
- **Source**: https://github.com/python-versioneer/python-versioneer
- **Homepage**: https://pypi.org/project/versioneer/
- **Language**: Python
- **GitHub**: 1,091 stars, 151 forks
- **Registry**: pypi (`versioneer`)
- **Tags**: `pypi`

## Description

The Versioneer
==============

* like a rocketeer, but for versions!
* https://github.com/python-versioneer/python-versioneer
* Brian Warner
* License: Public Domain (Unlicense)
* Compatible with: Python 3.7, 3.8, 3.9, 3.10, 3.11 and pypy3
* [![Latest Version][pypi-image]][pypi-url]
* [![Build Status][travis-image]][travis-url]

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](https://github.com/conda-forge/versioneer-feedstock) 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](INSTALL.md))
   * 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](https://github.com/conda-forge/versioneer-feedstock) 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](INSTALL.md))
* add `versioneer` (with `[toml]` extra, if configuring in `pyproject.toml`)
  to the `requires` key of the `build-system` table in `pyproject.toml`:
  ```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 ($Id$, etc)
* a `_version.py` created by some earlier build step

For released software, the version identifier is closely related to a VCS
tag. Some projects use tag names that include more than just the version
string (e.g. "myproject-1.2" instead of just "1.2"), in which case the tool
needs to strip the tag prefix to extract the version identifier. For
unreleased software (between tags), the version identifier should provide
enough information to help developers recreate the same tree, while also
giving them an idea of roughly how old the tree is (after version 1.2, before
version 1.3). Many VCS systems can report a description that captures this,
for example `git describe --tags --dirty --always` reports things like
"0.7-1-g574ab98-dirty" to indicate that the checkout is one revision past the
0.7 tag, has a unique revision id of "574ab98", and is "dirty" (it has
uncommitted changes).

The version identifier is used for multiple purposes:

* to allow the module to self-identify its version: `myproject.__version__`
* to choose a name and prefix for a 'setup.py sdist' tarball

## Theory of Operation

Versioneer works by adding a special `_version.py` file into your source
tree, where your `__init__.py` can import it. This `_version.py` knows how to
dynamically ask the VCS tool for version information at import time.

`_version.py` also contains `$Revision$` markers, and the installation
process marks `_version.py` to have this marker rewritten with a tag name
during the `git archive` command. As a result, generated tarballs will
contain enough information to get the proper version.

To allow `setup.py` to compute a version too, a `versioneer.py` is added to
the top level of your source tree, next to `setup.py` and the `setup.cfg`
that configures it. This overrides several distutils/setuptools commands to
compute the version when invoked, and changes `setup.py bui

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `0.29` | 2026-04-21 | Low | Imported from PyPI (0.29) |
| `0.28` | 2022-10-27 | Low | ## Release Notes  This release adds official support for Python 3.11, including using the built-in tomllib instead of the third-party tomli, when available.  ## What's Changed * FIX: handle unset versionfile_build in build_ext by @mgorny in https://github.com/python-versioneer/python-versioneer/pull/347 * ENH: support built-in tomllib for Python 3.11+ by @mgorny in https://github.com/python-versioneer/python-versioneer/pull/348  **Full Changelog**: https://github.com/python-versioneer/py |
| `0.27` | 2022-10-19 | Low | ## Release Notes  This release fixes a bug with non-isolated builds of Versioneer and for packages that provide their own `sdist` command.  With thanks to Dimitri Papadopoulos and Michal Gorny for contributions.  ## What's Changed  * FIX: Always bootstrap in setup.py to avoid incompatibility with old versioneer by @mgorny (#344) * FIX: Mixup between `_egg_info` and `_sdist` by @DimitriPapadopoulos (#342) * STY: Merge `endswith` checks by @DimitriPapadopoulos (#337) * STY: Useless inhe |
| `0.24` | 2022-08-31 | Low | ## What's Changed * MNT: Relicense to Unlicense by @effigies in https://github.com/python-versioneer/python-versioneer/pull/317 * ENH: in verbose mode do not hide stderr of git rev-parse by @yarikoptic in https://github.com/python-versioneer/python-versioneer/pull/318 * DOC: clarify upgrading to 0.23 doesn't require special actions by @sappelhoff in https://github.com/python-versioneer/python-versioneer/pull/321 * ENH: Prepare for py2exe dropping distutils support by @effigies in https://git |
| `0.23` | 2022-08-12 | Low | ## What's Changed * MNT: Drop 3.6 support, remove old hacks by @effigies in https://github.com/python-versioneer/python-versioneer/pull/288 * Clarify license as CC0-1.0 by @BastianZim in https://github.com/python-versioneer/python-versioneer/pull/292 * MNT: Drop distutils by @effigies in https://github.com/python-versioneer/python-versioneer/pull/289 * FIX: Restore py_modules field to setup.py by @effigies in https://github.com/python-versioneer/python-versioneer/pull/293 * Update URL of to |

## Citation

- HTML: https://www.freshcrate.ai/projects/versioneer
- Markdown: https://www.freshcrate.ai/projects/versioneer.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/versioneer/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._