semantic-versions 1.0.0

Reference implementation of Semantic Versions (semver.xyz): parse, compare and range-match versions, with builds that participate in precedence, pre-release and build channels, and contexts.
Documentation

semantic-versions

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

crates.io docs.rs spec

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

cargo add semantic-versions

Usage

use semantic_versions::{max_satisfying, satisfies, valid_range, Range, Version};

let v: Version = "1.2.3-beta.4+build.7".parse().unwrap();
assert_eq!((v.major, v.minor, v.patch), (1, 2, 3));

// Builds participate in precedence: a build ranks above its plain release.
assert!(Version::parse("1.0.0").unwrap() < Version::parse("1.0.0+build.1").unwrap());

assert!(satisfies("1.4.0", "^1.2.3"));
assert!(satisfies("1.0.0-rc.1", "^1.0.0-rc"));   // pre-release channel
assert!(!satisfies("1.0.0-beta", "^1.0.0-rc"));  // a different channel
assert!(satisfies("1.4.2+win.x64", "^1.0.0+win")); // build channel
assert_eq!(valid_range("~>1.2").as_deref(), Some(">=1.2.0 <1.3.0-0"));

// Contexts scope a version or range to an identity.
let range = Range::parse("npm:react@^18").unwrap();
assert!(range.test(&"npm:react@18.2.0".parse().unwrap()));
assert!(!range.test(&"cargo:react@18.2.0".parse().unwrap()));

assert_eq!(max_satisfying(["1.0.0", "1.9.0", "2.0.0"], "^1"), Some("1.9.0"));

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 bare 1.2.3 means ^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.3 and 1.2 are 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.