# semantic-version

> A library implementing the 'SemVer' scheme.

- **URL**: https://www.freshcrate.ai/projects/semantic-version
- **Author**: Raphaël Barrois
- **Category**: Frameworks
- **Latest version**: `2.10.0` (2026-04-21)
- **License**: BSD
- **Source**: https://github.com/rbarrois/python-semanticversion
- **Language**: Python
- **GitHub**: 292 stars, 73 forks
- **Registry**: pypi (`semantic-version`)
- **Tags**: `pypi`, `semantic`, `version`, `versioning`

## Description

Introduction
============

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.

.. image:: https://github.com/rbarrois/python-semanticversion/actions/workflows/test.yml/badge.svg
    :target: https://github.com/rbarrois/python-semanticversion/actions/workflows/test.yml

.. image:: https://img.shields.io/pypi/v/semantic_version.svg
    :target: https://python-semanticversion.readthedocs.io/en/latest/changelog.html
    :alt: Latest Version

.. image:: https://img.shields.io/pypi/pyversions/semantic_version.svg
    :target: https://pypi.python.org/pypi/semantic_version/
    :alt: Supported Python versions

.. image:: https://img.shields.io/pypi/wheel/semantic_version.svg
    :target: https://pypi.python.org/pypi/semantic_version/
    :alt: Wheel status

.. image:: https://img.shields.io/pypi/l/semantic_version.svg
    :target: https://pypi.python.org/pypi/semantic_version/
    :alt: License

Links
-----

- Package on `PyPI`_: https://pypi.org/project/semantic-version/
- Doc on `ReadTheDocs <http://readthedocs.org/>`_: https://python-semanticversion.readthedocs.io/
- Source on `GitHub <http://github.com/>`_: http://github.com/rbarrois/python-semanticversion/
- Build on Github Actions: https://github.com/rbarrois/python-semanticversion/actions
- Semantic Version specification: `SemVer`_


Getting started
===============

Install the package from `PyPI`_, using pip:

.. code-block:: sh

    pip install semantic-version

Or from GitHub:

.. code-block:: sh

    $ git clone git://github.com/rbarrois/python-semanticversion.git


Import it in your code:


.. code-block:: python

    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.

Versions
--------

Defining a ``Version`` is quite simple:


.. code-block:: pycon

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

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

.. code-block:: pycon

    >>> 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/base.py", line 64, in __init__
        major, minor, patch, prerelease, build = self.parse(version_string, partial)
      File "/Users/rbarrois/dev/semantic_version/src/semantic_version/base.py", line 86, in parse
        raise ValueError('Invalid version string: %r' % version_string)
    ValueError: Invalid version string: '0.1'


One may also create a ``Version`` with named components:

.. code-block:: pycon

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

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

.. code-block:: pycon

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


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:

.. code-block:: pycon

    >>> Version.coerce('0')
    Version('0.0.0')
    >>> Version.coerce('0.1.2.3.4')
    Version('0.1.2+3.4')
    >>> Version.coerce('0.1.2a3')
    Version('0.1.2-a3')

Working with versions
"""""""""""""""""""""

Obviously, versions can be compared:


.. code-block:: pycon

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

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

.. code-block:: pycon

    >>> v = semantic_version.Version('0.1.1+build')
    >>> new_v = v.next_major()
    >>> str(new_v)
    '1.0.0'
    >>> v = semantic_version.Version('1.1.1+build')
    >>> new_v = v.next_minor()
    >>> str(new_v)
    '1.2.0'
    >>> v = semantic_version.Version('1.1.1+build')
    >>> new_v = v.next_patch()
    >>> str(new_v)
    '1.1.2'



Requirement specification
-------------------------

python-semanticversion provides a couple of ways to describe a range of accepted
versions:

- The ``SimpleSpec`` class provides a simple, easily understood scheme --
  somewhat inspired from PyPI range notations;
- The ``NpmSpec`` class supports the whole NPM range spe

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `2.10.0` | 2026-04-21 | Low | Imported from PyPI (2.10.0) |
| `master@2024-04-04` | 2024-04-04 | Low | Latest activity on master branch |
| `master@2024-04-04` | 2024-04-04 | Low | Latest activity on master branch |
| `master@2024-04-04` | 2024-04-04 | Low | Latest activity on master branch |
| `master@2024-04-04` | 2024-04-04 | Low | Latest activity on master branch |
| `master@2024-04-04` | 2024-04-04 | Low | Latest activity on master branch |
| `master@2024-04-04` | 2024-04-04 | Low | Latest activity on master branch |
| `master@2024-04-04` | 2024-04-04 | Low | Latest activity on master branch |
| `master@2024-04-04` | 2024-04-04 | Low | Latest activity on master branch |
| `master@2024-04-04` | 2024-04-04 | Low | Latest activity on master branch |

## Citation

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

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