SemVer Parser & Comparator

What is a semantic version parser?#

Semantic Versioning (SemVer) is the major.minor.patch convention that most libraries use to signal what kind of change a release contains: a bug fix bumps patch, backwards-compatible additions bump minor, and breaking changes bump major. Add a pre-release tag (1.0.0-beta.1) or build metadata (+exp.sha.1) and you get the full grammar defined at semver.org 2.0.0.

The trouble is that “compare two versions” and “does this version satisfy my dependency range” are easy to get wrong by eye. Is 1.0.0 higher or lower than 1.0.0-beta? (Higher — a release always outranks its pre-release.) Does 1.2.3 satisfy ^1.2.0? (Yes.) Does it satisfy ~1.2.0? (Also yes, but for a tighter reason.) This page parses versions the way the spec defines them, shows you the components, compares two versions by precedence, and answers range queries with the same ^ / ~ / >= / || / hyphen syntax that a package.json uses — all locally, against the real rules rather than a guess.

How to use it#

1. Use the quick-fill buttons at the top to drop in common examples, or type directly.
2. Enter Version A and Version B in the two inputs. A leading v or = is accepted and stripped; 1.2.3-beta.1+build.42 is parsed down to its parts.
3. Enter a Range expression if you want a satisfaction check. The default is ^1.2.0 || >=2.0.0 <3.0.0 — two OR’d sets, the way real dependency ranges are written. Supported syntax: ^ (caret), ~ (tilde), >= <= > < =, x / X / * wildcards, partial versions (1.2), - hyphen ranges, and || to OR sets.
4. Read the two parse cards. Each shows the canonical clean form and the broken-out major, minor, patch, prerelease, and build fields. An invalid version turns its card red with a message.
5. Read the compare card. It lays out A < B, A = B, or A > B by precedence, plus the diff — the highest component that changed (major, minor, patch, prerelease, or build).
6. Read the range check card. It tells you, for the range you typed, whether A satisfies it and whether B satisfies it.

Key features#

• Precedence by the spec. Comparison walks major.minor.patch and then the pre-release identifiers, with the rule that a version without a pre-release always outranks one with. Numeric identifiers compare numerically (beta.2 < beta.11); alphanumeric ones compare lexically; and numeric always ranks below alphanumeric. Build metadata is parsed and displayed but never affects precedence.
• Caret and tilde, desugared correctly. ^1.2.3 becomes >=1.2.3 <2.0.0; ^0.2.3 becomes >=0.2.3 <0.3.0; ^0.0.3 becomes >=0.0.3 <0.0.4 — the caret’s “leftmost non-zero” rule. Tilde pins to the same minor: ~1.2.3 is >=1.2.3 <1.3.0.
• Ranges with ||, hyphens, and wildcards. ^1.0.0 || >=2.0.0 <3.0.0 (OR of two sets), 1.2.0 - 1.5.0 (inclusive hyphen range), 1.x / 1.2.* (wildcard ranges) all parse and test.
• The pre-release inclusion gate. A pre-release version can satisfy a range only when some comparator in the same set carries a pre-release tag on the same major.minor.patch. So 1.5.0-rc.1 does not satisfy ^1.2.0, but it does satisfy ^1.5.0-rc.0 — matching how real package managers keep random pre-releases out of your release builds.
• Diff that tells a story. The diff field reports the highest component that changed, so a jump from 1.2.3 to 2.0.0 shows major, and 1.0.0 to 1.0.0 with a changed build shows build even though precedence is unchanged.
• Forgiving input. Leading v, a leading =, and surrounding whitespace are tolerated, so versions copied from a git tag or a changelog parse without manual cleanup.

Worked example#

With the defaults — A 1.2.3, B 2.0.0, range ^1.2.0 || >=2.0.0 <3.0.0 — the page reports:

A clean    1.2.3        (major 1, minor 2, patch 3)
B clean    2.0.0        (major 2, minor 0, patch 0)
compare    1.2.3  <  2.0.0
diff       major
range      A satisfies   B satisfies

Both versions satisfy the range, but for different reasons: A falls inside the first OR set (^1.2.0 → >=1.2.0 <2.0.0), B falls inside the second (>=2.0.0 <3.0.0). Change B to 3.0.0 and its badge flips to not satisfies — the upper bound <3.0.0 excludes it.

To see the pre-release rule in action, set A to 1.5.0-rc.1 and B to 1.5.0, and keep the range as ^1.5.0-rc.0. Now A satisfies (same 1.5.0, the range carries a matching pre-release tag), while a plain ^1.5.0 would not let 1.5.0-rc.1 through — the gate exists precisely to keep release candidates out of release dependency resolution until you opt in.

FAQ#

Is 1.0.0 higher than 1.0.0-beta?#

Yes. A version with no pre-release tag always has higher precedence than one with a pre-release tag, even at the same major.minor.patch. So 1.0.0 > 1.0.0-rc.1 > 1.0.0-beta.11 > 1.0.0-alpha. This is why a release “going gold” is a real precedence bump, not just a label change.

What is the difference between ^ and ~?#

The caret allows updates that do not modify the left-most non-zero component: ^1.2.3 permits any 1.x.x from 1.2.3 up to (but not including) 2.0.0. The tilde is stricter — it pins the minor when given a full version: ~1.2.3 permits only 1.2.x. Given only a major (~1), tilde and caret both allow the whole major range. Most libraries pin with ^; patches to your own published packages often use ~.

Why does my pre-release version not satisfy ^1.0.0?#

By design. A pre-release like 1.5.0-rc.1 only satisfies a range when some comparator in the same AND-set has a pre-release tag on the same 1.5.0. ^1.0.0 desugars to >=1.0.0 <2.0.0-0 with no pre-release on 1.5.0, so the gate keeps your release build from pulling in someone’s random release candidate. If you want to opt in, write ^1.5.0-rc.0 explicitly.

Does build metadata affect comparison?#

No. 1.0.0+exp.sha.5 and 1.0.0+exp.sha.6 have equal precedence — build metadata is for identification only. The parser still shows it (and the diff reports a build change when only metadata differs), but it never decides an ordering.