Semantic Versioning (semver)

3.0.4 · active · verified Sat Mar 28

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.

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 Direct comparison between a `VersionInfo` object and a raw version string (e.g., `version_obj == '1.2.3'`) works, but for complex comparisons or expressions, always use `VersionInfo.parse()` for strings or the `match()` method.
Fix: For precise and reliable version logic, consistently convert strings to `VersionInfo` objects or use the `match()` method for expression-based checks. E.g., `VersionInfo.parse('1.0.0') == VersionInfo.parse('1.0.0')` or `version.match('~=1.0.0')`.

Install

pip install semver Install stable version

Imports

VersionInfo
```
from semver import VersionInfo
```
parse
```
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
```
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

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')}")

view raw JSON →