skip to navigation
skip to content

semantic_version 2.6.0

A library implementing the 'SemVer' scheme.

Package Documentation


This small python library provides a few tools to handle SemVer in Python. It follows strictly the 2.0.0 version of the SemVer scheme.

Getting started

Install the package from PyPI, using pip:

pip install semantic_version

Or from GitHub:

$ git clone git://

Import it in your code:

import semantic_version

This module provides two classes to handle semantic versions:

  • Version represents a version number (0.1.1-alpha+build.2012-05-15)
  • Spec represents a requirement specification (>=0.1.1,<0.3.0)


Defining a Version is quite simple:

>>> import semantic_version
>>> v = semantic_version.Version('0.1.1')
>>> v.major
>>> v.minor
>>> v.patch
>>> v.prerelease
>>> list(v)
[0, 1, 1, [], []]

If the provided version string is invalid, a ValueError will be raised:

>>> semantic_version.Version('0.1')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/rbarrois/dev/semantic_version/src/semantic_version/", line 64, in __init__
    major, minor, patch, prerelease, build = self.parse(version_string, partial)
  File "/Users/rbarrois/dev/semantic_version/src/semantic_version/", line 86, in parse
    raise ValueError('Invalid version string: %r' % version_string)
ValueError: Invalid version string: '0.1'

In order to define “relaxed” version strings, you must pass in partial=True:

>>> v = semantic_version.Version('0.1', partial=True)
>>> list(v)
[0, 1, None, None, None]

Obviously, Versions can be compared:

>>> semantic_version.Version('0.1.1') < semantic_version.Version('0.1.2')
>>> semantic_version.Version('0.1.1') > semantic_version.Version('0.1.1-alpha')
>>> semantic_version.Version('0.1.1') <= semantic_version.Version('0.1.1-alpha')

You can also get a new version that represents a bump in one of the version levels:

>>> v = semantic_version.Version('0.1.1-pre+build')
>>> new_v = v.next_major()
>>> str(new_v)
>>> v = semantic_version.Version('1.1.1-pre+build')
>>> new_v = v.next_minor()
>>> str(new_v)
>>> v = semantic_version.Version('1.1.1-pre+build')
>>> new_v = v.next_patch()
>>> str(new_v)

It is also possible to check whether a given string is a proper semantic version string:

>>> semantic_version.validate('0.1.3')
>>> semantic_version.validate('0a2')

Requirement specification

The Spec object describes a range of accepted versions:

>>> s = Spec('>=0.1.1')  # At least 0.1.1
>>> s.match(Version('0.1.1'))
>>> s.match(Version('0.1.1-alpha1'))  # pre-release satisfy version spec
>>> s.match(Version('0.1.0'))

Simpler test syntax is also available using the in keyword:

>>> s = Spec('==0.1.1')
>>> Version('0.1.1-alpha1') in s
>>> Version('0.1.2') in s

Combining specifications can be expressed in two ways:

  • Components separated by commas in a single string:

    >>> Spec('>=0.1.1,<0.3.0')
  • Components given as different arguments:

    >>> Spec('>=0.1.1', '<0.3.0')
  • A mix of both versions:

    >>> Spec('>=0.1.1', '!=0.2.4-alpha,<0.3.0')

Using a specification

The Spec.filter method filters an iterable of Version:

>>> s = Spec('>=0.1.0,<0.4.0')
>>> versions = (Version('0.%d.0' % i) for i in range(6))
>>> for v in s.filter(versions):
...     print v

It is also possible to select the ‘best’ version from such iterables:

>>> s = Spec('>=0.1.0,<0.4.0')
>>> versions = (Version('0.%d.0' % i) for i in range(6))

Coercing an arbitrary version string

Some user-supplied input might not match the semantic version scheme. For such cases, the Version.coerce method will try to convert any version-like string into a valid semver version:

>>> Version.coerce('0')
>>> Version.coerce('')
>>> Version.coerce('0.1.2a3')

Including pre-release identifiers in specifications

When testing a Version against a Spec, comparisons are only performed for components defined in the Spec; thus, a pre-release version (1.0.0-alpha), while not strictly equal to the non pre-release version (1.0.0), satisfies the ==1.0.0 Spec.

Pre-release identifiers will only be compared if included in the Spec definition or (for the empty pre-release number) if a single dash is appended (1.0.0-):

>>> Version('0.1.0-alpha') in Spec('>=0.1.0')  # No pre-release identifier
>>> Version('0.1.0-alpha') in Spec('>=0.1.0-')  # Include pre-release in checks

Including build metadata in specifications

Build metadata has no ordering; thus, the only meaningful comparison including build metadata is equality.

>>> Version('1.0.0+build2') in Spec('<=1.0.0')   # Build metadata ignored
>>> Version('1.0.0+build2') in Spec('==1.0.0+build2')  # Include build in checks

Using with Django

The semantic_version.django_fields module provides django fields to store Version or Spec objects.

More documentation is available in the django section.


In order to contribute to the source code:

When submitting patches or pull requests, you should respect the following rules:

  • Coding conventions are based on 8
  • The whole test suite must pass after adding the changes
  • The test coverage for a new feature must be 100%
  • New features and methods should be documented in the reference section and included in the changelog
  • Include your name in the contributors section


All files should contain the following header:

# -*- encoding: utf-8 -*-
# Copyright (c) The python-semanticversion project



reference django changelog credits

Indices and tables

  • genindex
  • modindex
  • search
File Type Py Version Uploaded on Size
semantic_version-2.6.0-py3-none-any.whl (md5) Python Wheel 3.3 2016-09-25 13KB
semantic_version-2.6.0.tar.gz (md5) Source 2016-09-25 13KB