semantic-versions
The Rust reference implementation of Semantic Versions: parse, validate, compare and range-match version numbers, with builds that participate in precedence.
It implements the specification and its
BNF grammars, and behaves identically to the
JavaScript reference parser (semantic-versions
on npm): both pass the same conformance suite,
and they agree on every version, range and resolution in the benchmark corpus.
No dependencies and no unsafe.
Install
Usage
use ;
let v: Version = "1.2.3-beta.4+build.7".parse.unwrap;
assert_eq!;
// Builds participate in precedence: a build ranks above its plain release.
assert!;
assert!;
assert!; // pre-release channel
assert!; // a different channel
assert!; // build channel
assert_eq!;
// Contexts scope a version or range to an identity.
let range = parse.unwrap;
assert!;
assert!;
assert_eq!;
How this differs from semver and nodejs-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. - npm-style range syntax (
>=1.2.0 <2.0.0,||,1.x,~,^,~>, hyphen ranges) rather than Cargo's comma-separated requirements, where a bare1.2.3means^1.2.3. Here a bare version means exactly that version. - Contexts:
npm:react@18.2.0,npm:@babel/core@^7. - No coercion:
v1.2.3and1.2are errors.
Performance and conformance
Compared with semver and
nodejs-semver on real versions and
dependency ranges from the npm registry. Method and raw results:
benchmarks/.
Speed
| Operation | semantic-versions@1.0.0 |
nodejs-semver@7.0.0 |
semver@1.0.28 |
semantic-versions vs nodejs-semver |
|---|---|---|---|---|
| Parse a version | 21.7 ns | 26.3 ns | 21.4 ns | 1.2× faster |
| Sort versions | 117 ns | 102 ns | 117 ns | 1.15× slower |
| Parse a range | 208 ns | 270 ns | — | 1.3× faster |
| Range::test(version) | 5.5 ns | 8.7 ns | — | 1.6× faster |
| Resolve a range | 1.03 µs | 1.32 µs | — | 1.3× faster |
Median time per operation (lower is better) on 5,398 published versions and 1,996 dependency ranges from the npm registry. rustc 1.97.0 · Intel(R) Xeon(R) Processor @ 2.30GHz · linux x86_64 · 2026-11-19. semver: Cargo's requirement syntax (bare versions mean ^, comparators are comma-separated, no || or hyphen ranges), so it is compared on versions only.
Conformance
| Semantic Versions feature | semantic-versions |
nodejs-semver |
semver |
|---|---|---|---|
| Version grammar Valid and invalid versions per the BNF | ✓ 81/81 | ◐ 59/81 | ✓ 81/81 |
No coercion Rejects v1.2.3, =1.2.3, 1.2.3pre, … |
✓ 11/11 | ◐ 3/11 | ✓ 11/11 |
| 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 | ✓ 10/10 |
Ranges Comparators, ||, x-ranges, ~, ^, hyphen ranges |
✓ 199/199 | ◐ 195/199 | ◐ 134/172 |
Approximate ranges The pessimistic operator ~> |
✓ 17/17 | ✓ 17/17 | ◐ 7/13 |
Pre-release channels ^1.0.0-rc admits rc.*, never beta |
✓ 44/44 | ◐ 33/44 | ◐ 34/44 |
Pre-release wildcards X.Y.Z-* and *-* opt in explicitly |
✓ 14/14 | ◐ 2/14 | ◐ 2/13 |
Build channels ^1.0.0+win admits +win.* builds only |
✓ 24/24 | ◐ 12/24 | ◐ 12/22 |
Contexts npm:react@18.2.0, npm:react@^18 |
✓ 15/15 | ◐ 3/15 | ◐ 3/15 |
| All cases | 447/447 | 357/447 | 326/413 |
Cases from the shared conformance suite in conformance/, drawn from the specification. ✓ all pass · ◐ some pass · ✗ none pass.
License
Apache License 2.0. The specification text at semver.xyz is licensed separately under CC BY 3.0.