Skip to main content

A library implementing the 'SemVer' scheme.

Project description


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. Latest Version Supported Python versions Wheel status License

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 classes to handle semantic versions:

  • Version represents a version number (0.1.1-alpha+build.2012-05-15)

  • BaseSpec-derived classes represent requirement specifications (>=0.1.1,<0.3.0):

    • SimpleSpec describes a natural description syntax

    • NpmSpec is used for NPM-style range descriptions.


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'

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+build')
>>> new_v = v.next_major()
>>> str(new_v)
>>> v = semantic_version.Version('1.1.1+build')
>>> new_v = v.next_minor()
>>> str(new_v)
>>> v = semantic_version.Version('1.1.1+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')

Finally, one may create a Version with named components instead:

>>> semantic_version.Version(major=0, minor=1, patch=2)

In that case, major, minor and patch are mandatory, and must be integers. prerelease and patch, if provided, must be tuples of strings:

>>> semantic_version.Version(major=0, minor=1, patch=2, prerelease=('alpha', '2'))

Requirement specification

The SimpleSpec object describes a range of accepted versions:

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

Simpler test syntax is also available using the in keyword:

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

Combining specifications can be expressed as follows:

>>> SimpleSpec('>=0.1.1,<0.3.0')

Using a specification

The SimpleSpec.filter method filters an iterable of Version:

>>> s = SimpleSpec('>=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 = SimpleSpec('>=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 SimpleSpec, comparisons are adjusted for common user expectations; thus, a pre-release version (1.0.0-alpha) will not satisfy the ==1.0.0 SimpleSpec.

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

>>> Version('0.1.0-alpha') in SimpleSpec('<0.1.0')  # No pre-release identifier
>>> Version('0.1.0-alpha') in SimpleSpec('<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 SimpleSpec('<=1.0.0')   # Build metadata ignored
>>> Version('1.0.0+build1') in SimpleSpec('==1.0.0+build2')  # Include build in checks

NPM-based ranges

The NpmSpec class handles NPM-style ranges:

>>> Version('1.2.3') in NpmSpec('1.2.2 - 1.4')
>>> Version('1.2.3') in NpmSpec('<1.x || >=1.2.3')

Refer to for a detailed description of NPM range syntax.

Using with Django

The semantic_version.django_fields module provides django fields to store Version or BaseSpec 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




reference django changelog credits

Indices and tables

  • genindex

  • modindex

  • search

Project details

Download files

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

Source Distribution

semantic_version-2.8.5.tar.gz (50.0 kB view hashes)

Uploaded source

Built Distribution

semantic_version-2.8.5-py2.py3-none-any.whl (15.4 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page