Skip to main content

provide package versions with version control data.

Project description

What is vcver?

vcver is an approach for versioning that heavily relies on the version control system of choice for determining version strings.

There are two categories of version strings:

develop versions, of the form:


With development branches, it is desired to not override versions published from a blessed subset of “released” branches. As such, if the current branch is not a release branch, a version of 0 is used instead of the main_version:{commit_count}+{branch}.{scm_change_id}

and a release version, of the form:


Each part is described as follows:

  • main_version is retrieved from the last tagged commit with a leading v (e.g. v1.0), but is converted to a 0 if the branch is not a release branch.
  • commit_count is the number of commits from main_version
  • branch is the branch that the repository was built against, removing characters that are incompatible with PEP440 (anything that is not alphanumeric or a dot)
  • scm_change_id is a unique id in the form of version control, used to identify the change that was used to build this version.

For example, in a git repository, on a master branch with the most recent tag of v1.1, the dev version would look something like:


On a develop branch:


And a release version:


These are compatible with PEP440.


Add a to your package, if you do not already have one. Then add the following:

include VERSION

It’s also recommended to ignore this file in your version control.

Then, follow this pattern in your

# OPTIONAL, but recommended:
# this block is useful for specifying when a build should
# use the 'release' version. it allows specifying a release version
# with an additional argument in the
# $ python upload --release
import sys
is_release = False
if "--release" in sys.argv:
    is_release = True

# OPTIONAL, but recommended:
# vcver writes a version file relative to the
# current working directory by default.
# It's recommended to provide it with your
# directory instead (in case someone
# runs your from a different directory)
base = os.path.dirname(os.path.abspath(__file__))

    # add the following two lines,
    # and do not specify a version.
    # vcver will only produce a release
    # version if "is_release" is True.
        "is_release": is_release,
        "path": base,

        # version_format overrides the standard version format

        # release_version_format overrides the release version format

        # scm_type: if you do not want autodetection of the SCM, you can
        # specify it.

        # release_branch_regex: override the default release branch
        # (default release branch depends on the SCM used.)

        # version_file: override the name of the version file.

Now your package will publish with a VC-based version!

If you followed the full example, you can specify the release version by adding –release:

python upload --release

FAQ / Other Details

Why a dev and release version?

The dev and release versions have different goals:

  • dev: to provide as much information as possible to quickly identify where the current version originated from in regard to version control.
  • release: to provide a clear version that helps the consumer understand what changed.

For most consumers, the number of commits since the last release, the branch it was released against, or the build commit itself are irrelevant. The consumer wants to know about the size of the change or type of changes, and that can be done by the major / minor / patch versions specified in the git tag, or the changelog. Adding version control information proves to be confusing with that regard, providing multiple numbers that are not relevant to figuring out the amount of change.

Why zero out versions from non-release branches?

Sometimes, a non-release version can be published accidentally, or it may be desired to publish development versions side by side by versions published by release branches. In this situations, ensuring that the release versions always take precedence over non-release version is valuable, to ensure that development versions are not accidentally picked up by those expecting stable releases.

If this behavior is not desired, custom version strings can be specified with “main_version” instead of “main_version”. “main_version” is preserved regardless of the branch used.

How to make sure others can consume your package

If you followed the example, you already have this.

Once vcver is called, a VERSION file is created in the current working directory, which is typically the same directory as where the lives (you can make it more accurate, see the example)

vcver will attempt to find a VERSION file if the working directory is not a version control repository. Make sure your package includes a VERSION file by creating/modifying the

include VERSION

Customizable Version Strings

Both the version format and release format is configurable, with the arguments version_format and release_version_format, respectively.

In addition to the values above, the following values are provided:

  • tag_version: the raw version of main_version, which does not zero out for non-release branches.

Pre-PEP440 Version

Some (much older) versions of setuptools are unable to consume the dev version string, due to the plus in the version string.

If you need backwards compatibility and you would still like vc versioning, the following format is recommended:


This can be changed by an argument into vcver:
# in the setup call of
vcver={"version_format": "{main_version}.dev{commit_count}.{branch}.{scm_change_id}"}

Compatibility with Semantic Versioning

Semantic versioning is a standard to provided a meaning to the major, minor, and patch versions of a version string. Compatibility with semver is possible if new major / minor versions are tagged according the semver spec.

Special Thanks

  • Zillow, where this particular approach of SCM-based versioning was developed
  • Taylor McKay, who implemented the original Python version at Zillow
  • Mohammad Sarhan, who designed and implemented the original Java version at Zillow, and has a public gradle variant

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for vcver, version 0.2.10
Filename, size File type Python version Upload date Hashes
Filename, size vcver-0.2.10-py2.py3-none-any.whl (13.2 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size vcver-0.2.10.tar.gz (12.3 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page