What is semantic versioning?

Semantic Versioning (semver, defined at semver.org) is a versioning scheme in which the three numbers in MAJOR.MINOR.PATCH carry a compatibility promise:

• MAJOR (e.g. 2.0.0) — you changed something in a backwards-incompatible way: removed a feature, changed an API, altered a default in a way that can break existing code.
• MINOR (e.g. 1.4.0) — you added functionality in a backwards-compatible way: new endpoints, new flags, new features old code can ignore.
• PATCH (e.g. 1.4.2) — you fixed a bug without changing behaviour.

Because the numbers encode meaning, a consumer can judge an upgrade from the version alone: anything in 1.x is (supposedly) compatible with what they already run, and ^1.4.2 in a dependency file means “give me the newest 1.x that is at least 1.4.2”.

How two versions compare

Comparison is strictly numeric, field by field, left to right:

1. Compare MAJOR as numbers. If they differ, the larger one is newer — stop.
2. Otherwise compare MINOR, then PATCH, the same way.
3. If the three numbers are equal, a version without a prerelease tag is newer than one with one: 1.0.0 > 1.0.0-rc.1.
4. Two prereleases compare identifier by identifier (the rules in the next section).
5. Build metadata (the +build part) is never compared — 1.0.0+build.1 and 1.0.0+build.99 have the same precedence.

The classic trap: 1.2.10 is newer than 1.2.9, even though a plain text sort puts 1.2.9 first (because “9” > “1” as characters). Every comparison on this page is numeric, so it gets that right.

Prerelease versions

A prerelease tag — 1.0.0-alpha, 2.1.0-rc.1 — marks a build that is not yet a full release. Precedence rules, applied in order:

• A prerelease has lower precedence than the associated normal version: 1.0.0-alpha < 1.0.0.
• Identifiers are compared left to right. Numeric identifiers compare as numbers: beta.2 < beta.11.
• Alphanumeric identifiers compare in ASCII (lexicographic) order: alpha < beta < rc.
• Numeric identifiers always sort before alphanumeric ones: alpha.1 < alpha.beta.
• A shorter set of identifiers sorts first when all preceding identifiers are equal: alpha < alpha.1.

Applied in sequence, the spec’s canonical ordering for 1.0.0 is:

Try any adjacent pair in the playground above and the calculator names the rule that decided it.

Build metadata

Everything after a + — 1.2.3+20190101, 1.2.3+sha.abc123 — is build metadata. It is recorded with the version but ignored when comparing precedence: two versions that differ only in build metadata are the same release for ordering purposes. The metadata exists so build systems can record how a release was built (commit hash, build number, timestamp) without changing its position in the ordering.

Version ranges

Package managers describe “which versions are acceptable” with range syntax. The range checker above implements the common npm-style grammar:

Syntax	Means
1.2.3	exactly 1.2.3
1.2.x or 1.2	any 1.2.* — >=1.2.0 <1.3.0
1.x or 1	any 1.* — >=1.0.0 <2.0.0
* or x	anything
^1.2.3	compatible with 1.2.3 — >=1.2.3 <2.0.0 (a new MAJOR may break you)
^0.2.3	>=0.2.3 <0.3.0 — under 1.0, the MINOR is the breaking unit
^0.0.3	>=0.0.3 <0.0.4 — with 0.0, only the exact patch is compatible
~1.2.3	patches only — >=1.2.3 <1.3.0
>=1.2.3 <2.0.0	explicit comparators, all must hold (AND)
1.0.0 - 2.0.0	hyphen range — >=1.0.0 <=2.0.0
1.2.3 || 3.x	either range (OR)

One subtlety worth knowing: by default, prerelease versions only match a range that explicitly names a prerelease on the same core version. ^1.2.3 matches 1.9.0 but not 1.9.0-rc.1; >=1.2.3-alpha does match 1.2.3-beta. This is standard npm behaviour — it keeps dependency resolution from silently pulling in prereleases.

Common pitfalls

• Text sorting versions. 1.2.9 > 1.2.10 as strings. Always compare numerically — that is what the sort tool above does.
• Caret under 0.x. ^0.2.3 does not allow 0.3.0, and ^0.0.3 allows only 0.0.3. If you need 0.x flexibility, write ~0.2.3 or >=0.2.3 <1.0.0 explicitly.
• Prerelease vs release. 1.0.0-rc.1 is older than 1.0.0, not newer. A release is the end of its own prerelease chain.
• Build metadata in ranges. 1.2.3+build.1 as a range means exactly 1.2.3 — the build part is ignored, so it does not match 1.2.3+build.2 any more than it excludes it.
• Leading zeros. Strict semver forbids them (01.2.3 is invalid). This calculator accepts them with a warning so it stays useful with sloppy real-world input.
• The v prefix. v1.2.3 and 1.2.3 are the same version; most tools (and this calculator) accept both.