Semantic Versioning Library

2.10.0 verified Tue May 12 auth: no python install: verified

This Python library provides tools to handle Semantic Versioning (SemVer) strictly following the 2.0.0 scheme. It offers classes for parsing, comparing, and manipulating version numbers and defining requirement specifications. As of version 2.10.0, it is actively maintained with a stable release cadence.

pip install semantic-version

Common errors

error ModuleNotFoundError: No module named 'semantic_version' ↓

cause The `semantic-version` package is not installed in the current Python environment.

fix

pip install semantic-version

error ValueError: Invalid version string '1.2' ↓

cause The input string provided to `semantic_version.Version()` does not strictly adhere to the Semantic Versioning 2.0.0 specification, which requires a MAJOR.MINOR.PATCH format.

fix

Ensure the version string is in the MAJOR.MINOR.PATCH format (e.g., '1.2.0'), or use Version.coerce() for more lenient parsing.

error ImportError: cannot import name 'SemanticVersion' from 'semantic_version' ↓

cause The main class for representing a semantic version in the `semantic-version` library is named `Version`, not `SemanticVersion`.

fix

Use from semantic_version import Version instead.

error TypeError: '<' not supported between instances of 'Version' and 'str' ↓

cause You are attempting to compare a `semantic_version.Version` object directly with a plain string, which is not directly supported by comparison operators.

fix

Convert the string to a semantic_version.Version object before comparison, e.g., version_obj > Version('1.0.0').

error ValueError: Invalid requirement string '~1.0' ↓

cause The input string for `semantic_version.Requirement()` does not follow the valid syntax for a requirement specification (e.g., the tilde operator requires a patch version).

fix

Provide a valid requirement string, such as ~=1.0.0 or >=1.0.0,<2.0.0.

Warnings

gotcha The library strictly adheres to Semantic Versioning 2.0.0. Attempting to parse or validate strings that do not conform to this specification will raise a `ValueError`. ↓

fix Ensure version strings are SemVer 2.0.0 compliant (e.g., '1.0.0', '1.2.3-alpha.1', '1.0.0+build.20230101'). Do not include a 'v' prefix.

gotcha Build metadata (the part after `+`, e.g., `+build.123`) is ignored when determining version precedence. This means `Version('1.0.0+abc') == Version('1.0.0+xyz')` is `True`. The `compare()` function may return `NotImplemented` if versions only differ by build metadata. ↓

fix Be aware that build metadata is purely for informational purposes and does not affect the order or equality of versions. If distinct versions are needed, ensure differences are in major, minor, patch, or pre-release components.

gotcha Pre-release identifiers (the part after `-`, e.g., `-alpha`) are compared lexicographically as ASCII strings, not numerically. Also, pre-release versions have lower precedence than their corresponding release version (e.g., `1.0.0-alpha < 1.0.0`). ↓

fix Understand that '1.0.0-alpha.1' comes before '1.0.0-alpha.2', but '1.0.0-beta' comes after '1.0.0-alpha' due to ASCII sorting. Case also matters (e.g., '1.0.0-alpha' < '1.0.0-Beta').

gotcha Using `Version(version_string, partial=True)` alters comparison behavior. If a component (minor, patch, prerelease, or build) was absent from the partial Version (represented with `None`), it is considered equal for comparison purposes. For instance, `Version('1.0', partial=True)` means 'any version beginning with 1.0'. ↓

fix Only use `partial=True` when intentionally desiring this flexible comparison behavior for incomplete version strings, such as matching a major.minor prefix.

gotcha The `SimpleSpec` and `NpmSpec` classes implement different version range specification schemes. `SimpleSpec` is intuitive and inspired by PyPI, while `NpmSpec` strictly follows NPM's complex rules (e.g., `~` and `^` operators have specific meanings). ↓

fix Choose the appropriate `Spec` class based on the desired range syntax. Familiarize yourself with the specifics of `NpmSpec` if integrating with systems that use NPM-style version ranges.

breaking The library's version range specification evaluation, particularly with `SimpleSpec` or default behavior, incorrectly evaluates strict inequality operators (`>` or `<`) at version boundaries. A version `X.Y.Z` might erroneously be considered to satisfy a spec requiring `>X.Y.Z` or `<X.Y.Z`. ↓

fix When defining version specifications, be aware that strict inequality operators (`>` and `<`) may not correctly exclude the boundary version. For strict exclusion, carefully test boundary conditions. If inclusive behavior is desired, explicitly use operators like `>=` or `<=`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.11s 17.9M

3.10 alpine (musl) - - 0.11s 17.9M

3.10 slim (glibc) wheel 1.5s 0.07s 18M

3.10 slim (glibc) - - 0.07s 18M

3.11 alpine (musl) wheel - 0.14s 19.7M

3.11 alpine (musl) - - 0.16s 19.7M

3.11 slim (glibc) wheel 1.6s 0.12s 20M

3.11 slim (glibc) - - 0.12s 20M

3.12 alpine (musl) wheel - 0.13s 11.6M

3.12 alpine (musl) - - 0.15s 11.6M

3.12 slim (glibc) wheel 1.4s 0.14s 12M

3.12 slim (glibc) - - 0.15s 12M

3.13 alpine (musl) wheel - 0.12s 11.4M

3.13 alpine (musl) - - 0.13s 11.3M

3.13 slim (glibc) wheel 1.5s 0.13s 12M

3.13 slim (glibc) - - 0.13s 12M

3.9 alpine (musl) wheel - 0.08s 17.4M

3.9 alpine (musl) - - 0.09s 17.4M

3.9 slim (glibc) wheel 1.8s 0.07s 18M

3.9 slim (glibc) - - 0.08s 18M

Imports

Version
```
from semantic_version import Version
```
SimpleSpec
```
from semantic_version import SimpleSpec
```
Used for simple, PyPI-inspired version range specifications.
NpmSpec
```
from semantic_version import NpmSpec
```
Used for NPM-style version range specifications.
compare, match, validate
```
from semantic_version import compare, match, validate
```
Module-level functions for version comparison, specification matching, and validation.

Quickstart last tested: 2026-04-24

This example demonstrates how to create Version objects, access their components, perform comparisons, and use SimpleSpec to check if a version falls within a specified range.

from semantic_version import Version, SimpleSpec

# Create a Version object
v = Version('1.2.3-alpha+build.123')
print(f"Version: {v}")
print(f"Major: {v.major}, Minor: {v.minor}, Patch: {v.patch}")
print(f"Prerelease: {v.prerelease}, Build: {v.build}")

# Compare versions
v1 = Version('1.0.0')
v2 = Version('1.0.1')
print(f"Is {v1} < {v2}? {v1 < v2}")

# Define and use a SimpleSpec
spec = SimpleSpec('>=1.0.0,<2.0.0')
print(f"Does {v1} match spec '>1.0.0,<2.0.0'? {v1 in spec}")
print(f"Does {v2} match spec '>1.0.0,<2.0.0'? {v2 in spec}")
print(f"Does Version('2.0.0') match spec '>1.0.0,<2.0.0'? {Version('2.0.0') in spec}")