Version Tools Documentation


Define single and useful __version__ of a project.

See also

To get started quickly see Usage

See also

See what’s new in Version 1.8.2


This document may be out of date, the bleeding edge version is always available at


  • Keep a single version definition inside your package or module
  • Get proper versioning of development snapshots coupled with your VCS (pluggable support for additional systems available). Git, Mercurial and Bazaar are supported out of the box.
  • Produce nice version strings for released files that are compliant with PEP 386
  • Remain comparable as tuple of integers

How version tuple affects version string

This is pulled from the documentation of the string method on the Version class. In general you don’t need to explicitly use that class to benefit from this system. To learn more check the Usage section.


Return a string representation of the version tuple.

The string is not a direct concatenation of all version components. Instead it’s a more natural ‘human friendly’ version where components with certain values are left out.

The following table shows how a version tuple gets converted to a version string.

__version__ Formatter version
(1, 2, 0, "final", 0) "1.2"
(1, 2, 3, "final", 0) "1.2.3"
(1, 3, 0, "alpha", 1) "1.3a1"
(1, 3, 0, "beta", 1) "1.3b1"
(1, 3, 0, "candidate", 1) "1.3c1"
(1, 3, 0, "dev", 0) ""

Now when release level is set to "dev" then interesting things start to happen. When possible, version control system is queried for revision or changeset identifier. This information gets used to create a more useful version string. The suffix gets appended to the base version string. So for example a full version string, when using Bazaar might look like this: "1.3.dev54" which indicates that the tree was at revision 54 at that time.

The following table describes what gets appended by each version control system.

VCS Formatted version suffix
Bazaar Revision number (revno), e.g. 54
Git Head commit ID (sha1), e.g. "e40105c58a162de822b63d28b63f768a9763fbe3"
Mercurial Tip revision number, e.g. 54


This logic is implemented in versiontools.Version.__str__() and can be overridden by sub-classes. You can use project-specific logic if required. To do that replace __version__ with an instance of your sub-class.

Table Of Contents

Next topic


This Page