Semantic Versioning (semver)

3.0.4 verified Tue May 12 auth: no python install: verified quickstart: stale

The `semver` library in Python helps developers work with Semantic Versioning (SemVer) specifications (semver.org). It provides tools for parsing, comparing, bumping, and formatting version strings according to the MAJOR.MINOR.PATCH scheme, including pre-release and build metadata. The library is actively maintained with releases as needed to address bugs and introduce new features, currently at version 3.0.4.

pip install semver

Common errors

error ValueError: Invalid version string: '1.2' ↓

cause The input string to `semver.Version.parse()` does not conform to the strict MAJOR.MINOR.PATCH format required by Semantic Versioning.

fix

Ensure the version string adheres to the 'MAJOR.MINOR.PATCH' format, e.g., '1.2.0' instead of '1.2'.

error AttributeError: module 'semver' has no attribute 'parse' ↓

cause In `semver` library version 3.x, the `parse` function is a static method of the `Version` class, not a top-level module function.

fix

Use semver.Version.parse() instead of semver.parse() to parse a version string.

error TypeError: expected string or bytes-like object, got NoneType ↓

cause The `semver.Version.parse()` method expects a string input, but received a non-string type (e.g., `None`, an integer, or a list).

fix

Ensure the input to semver.Version.parse() is a valid string representation of a semantic version.

error TypeError: 'a' is not a valid int for patch ↓

cause When directly constructing a `semver.Version` object, the major, minor, and patch components must be valid integers, but a non-integer or non-numeric string was provided.

fix

Provide integer values for the major, minor, and patch components, e.g., semver.Version(1, 2, 3).

error AttributeError: can't set attribute 'major' ↓

cause `semver.Version` objects are immutable; their attributes (major, minor, patch, prerelease, etc.) cannot be changed directly after creation.

fix

To modify a version, use the provided bump_* methods (e.g., v.bump_major()) or create a new Version object with the desired changes.

Warnings

breaking Major breaking change in `semver` version 3.x: All module-level functions (e.g., `semver.parse()`, `semver.compare()`, `semver.bump_major()`) have been removed. ↓

fix Migrate to the object-oriented `VersionInfo` class. For parsing, use `VersionInfo.parse()`. For comparisons, instantiate `VersionInfo` objects and use standard Python comparison operators (e.g., `v1 < v2`). For bumping, use `version_obj.bump_major()`, `version_obj.bump_minor()`, etc.

deprecated Module-level functions were deprecated in `semver` version 2.10.0 and above. ↓

fix While still functional in 2.x, it's recommended to update your code to use the `VersionInfo` class methods to ensure compatibility with 3.x.

gotcha The `VersionInfo.match()` method expects a single comparison expression (e.g., `'>=1.2.0'`, `'~=1.0.0'`, `'^1.0.0'`) as its argument. Passing multiple conditions combined in a single string (e.g., `'>=1.2.0 <2.0.0'`) will result in a `ValueError` because it attempts to parse the entire string as a single invalid semantic version. ↓

fix When checking for multiple conditions (e.g., a version range), make separate `match()` calls and combine them with logical operators. For example, instead of `version.match('>=1.2.0 <2.0.0')`, use `version.match('>=1.2.0') and version.match('<2.0.0')`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.03s 17.9M

3.10 alpine (musl) - - 0.03s 17.9M

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

3.10 slim (glibc) - - 0.02s 18M

3.11 alpine (musl) wheel - 0.06s 19.7M

3.11 alpine (musl) - - 0.07s 19.7M

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

3.11 slim (glibc) - - 0.05s 20M

3.12 alpine (musl) wheel - 0.07s 11.6M

3.12 alpine (musl) - - 0.06s 11.6M

3.12 slim (glibc) wheel 1.5s 0.06s 12M

3.12 slim (glibc) - - 0.06s 12M

3.13 alpine (musl) wheel - 0.05s 11.4M

3.13 alpine (musl) - - 0.06s 11.3M

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

3.13 slim (glibc) - - 0.06s 12M

3.9 alpine (musl) wheel - 0.03s 17.4M

3.9 alpine (musl) - - 0.03s 17.4M

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

3.9 slim (glibc) - - 0.03s 18M

Imports

VersionInfo
```
from semver import VersionInfo
```
parse
wrong
```
import semver; semver.parse('1.2.3')
```
correct
```
from semver import VersionInfo
```
Module-level functions like `semver.parse()` were deprecated in 2.10.0 and removed in 3.x. Use `VersionInfo.parse()` instead.
compare
wrong
```
import semver; semver.compare('1.0.0', '2.0.0')
```
correct
```
from semver import VersionInfo; v1 = VersionInfo.parse('1.0.0'); v2 = VersionInfo.parse('2.0.0'); v1 < v2
```
Module-level comparison functions like `semver.compare()` were deprecated in 2.10.0 and removed in 3.x. Use `VersionInfo` objects with standard comparison operators.

Quickstart stale last tested: 2026-04-23

This quickstart demonstrates how to parse version strings into `VersionInfo` objects, access their components, compare different versions using standard operators, bump version parts, and check against match expressions. This uses the recommended object-oriented approach.

from semver import VersionInfo

# Parse a version string
version = VersionInfo.parse("1.2.3-alpha.1+build.123")
print(f"Parsed version: {version}")
print(f"Major: {version.major}, Minor: {version.minor}, Patch: {version.patch}")

# Compare versions
v1 = VersionInfo.parse("1.0.0")
v2 = VersionInfo.parse("1.0.1")
v3 = VersionInfo.parse("2.0.0")

print(f"Is v1 < v2? {v1 < v2}")
print(f"Is v3 > v1? {v3 > v1}")
print(f"Is v1 == '1.0.0'? {v1 == '1.0.0'}") # Can compare with strings too

# Bump a version
next_minor = version.bump_minor()
print(f"Next minor version: {next_minor}")

# Check if a version matches an expression
print(f"Does {version} match '>=1.2.0 <2.0.0'? {version.match('>=1.2.0 <2.0.0')}")