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.3and1.2are 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.