Skip to main content

semantic-versions

The Python implementation of Semantic Versions: parse, validate, compare and range-match version numbers, with builds that participate in precedence.

It is a port of the JavaScript reference implementation (semantic-versions on npm) and behaves identically: both pass the same conformance suite, and they agree on every version, range and resolution in the benchmark corpus. Pure Python 3.10+, typed, no dependencies.

Install

pip install semantic-versions

Usage

import semantic_versions as sv

v = sv.parse("1.2.3-beta.4+build.7")
assert (v.major, v.minor, v.patch, v.pre, v.build) == (1, 2, 3, "beta.4", "build.7")

# Builds participate in precedence: a build ranks above its plain release.
assert sv.parse("1.0.0") < sv.parse("1.0.0+build.1")

assert sv.satisfies("1.4.0", "^1.2.3")
assert sv.satisfies("1.0.0-rc.1", "^1.0.0-rc")      # pre-release channel
assert not sv.satisfies("1.0.0-beta", "^1.0.0-rc")  # a different channel
assert sv.satisfies("1.4.2+win.x64", "^1.0.0+win")  # build channel
assert sv.valid_range("~>1.2") == ">=1.2.0 <1.3.0-0"

# Contexts scope a version or range to an identity.
react = sv.Range("npm:react@^18")
assert sv.parse("npm:react@18.2.0") in react
assert sv.parse("pypi:react@18.2.0") not in react

assert sv.max_satisfying(["1.0.0", "1.9.0", "2.0.0"], "^1") == "1.9.0"
assert sv.sort(["2.0.0", "1.0.0+b", "1.0.0"]) == ["1.0.0", "1.0.0+b", "2.0.0"]
assert sv.valid("v1.2.3") is None  # no coercion

parse raises InvalidVersion and Range() raises InvalidRange (both ValueErrors); valid, valid_range, satisfies and friends return None or False instead.

How this differs from node-semver and semver

  • Builds participate in precedence (1.0.0 < 1.0.0+build), and a build on a comparator is a channel filter.
  • Pre-releases are range-driven: a pre-release on a comparator is a prefix channel scoped to its tuple; X.Y.Z-* and *-* opt in explicitly.
  • Contexts: npm:react@18.2.0, npm:@babel/core@^7.
  • No coercion: v1.2.3 and 1.2 are errors.
  • npm-style ranges (>=1.2.0 <2.0.0, ||, 1.x, ~, ^, ~>, hyphen ranges), which python-semver does not have.

Performance and conformance

Compared with node-semver and semver on real versions and dependency ranges from the npm registry. Method and raw results: benchmarks/. All implementations: semver.xyz/libraries.

Speed

Operation semantic-versions@1.0.0 node-semver@0.9.1 semver@3.1.2 semantic-versions vs node-semver
Parse a version 920 ns 1.44 µs 1.38 µs 1.6× faster
Sort versions 657 ns 9.90 µs 5.89 µs 15× faster
Parse a range 4.30 µs 16.0 µs — 3.7× faster
range.test(version) 247 ns 1.76 µs — 7.1× faster
Resolve a range 39.9 µs 267.3 µs — 6.7× faster

Median time per operation (lower is better) on 5,398 published versions and 1,996 dependency ranges from the npm registry. CPython 3.13.18 · Intel(R) Xeon(R) Processor @ 2.30GHz · linux x86_64 · 2026-11-19. semver: python-semver has no npm-style ranges (only single comparisons such as >=1.2.3), so it is compared on versions only.

Conformance

Semantic Versions feature semantic-versions node-semver semver
Version grammar
Valid and invalid versions per the BNF
✓ 81/81 ◐ 80/81 ◐ 80/81
No coercion
Rejects v1.2.3, =1.2.3, 1.2.3pre, …
✓ 11/11 ◐ 10/11 ✓ 7/7
Precedence
Major, minor, patch and pre-release ordering
✓ 32/32 ✓ 32/32 ✓ 32/32
Build precedence
A build ranks above its release: 1.0.0 < 1.0.0+b
✓ 10/10 ◐ 1/10 ◐ 1/10
Ranges
Comparators, ||, x-ranges, ~, ^, hyphen ranges
✓ 199/199 ◐ 174/199 — n/a
Approximate ranges
The pessimistic operator ~>
✓ 17/17 ◐ 13/17 — n/a
Pre-release channels
^1.0.0-rc admits rc.*, never beta
✓ 44/44 ◐ 33/44 — n/a
Pre-release wildcards
X.Y.Z-* and *-* opt in explicitly
✓ 14/14 ◐ 2/14 — n/a
Build channels
^1.0.0+win admits +win.* builds only
✓ 24/24 ◐ 12/24 — n/a
Contexts
npm:react@18.2.0, npm:react@^18
✓ 15/15 ◐ 3/15 ✗ 0/8
All cases 447/447 360/447 120/138

Cases from the shared conformance suite in conformance/, drawn from the specification. ✓ all pass · ◐ some pass · ✗ none pass.

Develop

python -m unittest discover -s tests       # conformance suite
pip install node-semver semver && python bench/compare.py

License

Apache-2.0. The specification is at semver.xyz.

Metadata

Release files for semantic-versions 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for semantic-versions 1.0.0
File Size Uploaded Provenance Actions
semantic_versions-1.0.0.tar.gz 16.7 kB Without provenance Details for semantic_versions-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for semantic-versions 1.0.0
File Interpreter ABI Platform Actions
semantic_versions-1.0.0-py3-none-any.whl Python 3 none any Details for semantic_versions-1.0.0-py3-none-any.whl

Total release size: 30.9 kB

Release files / semantic_versions-1.0.0.tar.gz

Download URL semantic_versions-1.0.0.tar.gz
Size 16.7 kB
Tags Source
SHA-256 checksum
How to use checksums
52ec244bd5f0e30b7d56c22296bd96b01f31032e73ae79ac99fb90b570bb05a9
BLAKE2b-256 checksum
How to use checksums
60fa9eb6e556410298a7ef3b60cb8ca6352e644ebb37008996d85836719de792
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.5

Release files / semantic_versions-1.0.0-py3-none-any.whl

Download URL semantic_versions-1.0.0-py3-none-any.whl
Size 14.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
70061a43f9f97593e0221ece283b11df3e011c5695b24e729c2d57fb617cd289
BLAKE2b-256 checksum
How to use checksums
2af5bc04435c9c8f9df32f0cf6d3669191d10c656dfe254528f518a241afa87a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.5

Security for semantic-versions 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page