🔢 Semantic Version Comparator

What is the Semver Comparator?

Semantic Versioning (semver) is a convention for numbering software releases so that the number itself carries meaning. A version has the shape MAJOR.MINOR.PATCH, such as 2.5.1. You bump the major number for breaking changes, the minor number for new but backward-compatible features, and the patch number for backward-compatible bug fixes. Optionally a hyphen introduces a prerelease label (1.0.0-rc.1) and a plus sign introduces build metadata (1.0.0+20130313144700). This shared grammar is what lets package managers like npm, Cargo and Composer reason about which versions satisfy a range.

Comparing two versions follows a strict precedence order. First the major, minor and patch numbers are compared numerically, left to right, and these are integers, not decimals, so 1.0.10 is greater than 1.0.9 (ten is more than nine) even though as a decimal 0.10 looks smaller than 0.9. Only if all three core numbers are identical does the prerelease section decide the order. A version that carries a prerelease label always ranks lower than the same version without one, because a prerelease comes before the final release it is leading up to: 1.0.0-rc.1 is less than 1.0.0.

When both versions are prereleases of the same core version, their labels are compared identifier by identifier, split on the dots. Numeric identifiers are compared as numbers and always rank below non-numeric ones, alphanumeric identifiers are compared in ASCII sort order, and if every shared identifier matches, the label with more identifiers wins. This gives the canonical chain 1.0.0-alpha is less than 1.0.0-alpha.1, which is less than 1.0.0-beta, which is less than 1.0.0-rc.1, which is less than 1.0.0. Build metadata (the part after the plus sign) is ignored entirely when comparing, so 1.0.0+build.1 and 1.0.0+build.99 have equal precedence.

When to use it

• Settling whether a deployed version is newer than the one in a changelog or lockfile before you roll back or upgrade.
• Checking that a release candidate or beta tag sorts below the final release it is meant to precede.
• Confirming that 1.0.10 is correctly treated as newer than 1.0.9, a frequent source of sorting bugs in naive string compares.
• Teaching or sanity-checking how npm, Cargo or Composer will order two versions when resolving a dependency range.

How to use the Semver Comparator

1. Type the first version into the Version A box, for example 1.2.3.
2. Type the second version into the Version B box, for example 1.2.3-rc.1.
3. Read the verdict: it tells you which version is greater, or that the two are equal in precedence.
4. Check the parsed parts below to see how each version split into major, minor, patch, prerelease and build.

Formula & method

Worked examples

Canonical semver precedence chain (lowest to highest)

What each part of a version means

Common mistakes to avoid

• Comparing versions as plain strings. A string compare puts 1.0.9 above 1.0.10 because the character 9 sorts after 1. Semver compares the patch numbers as integers, so 1.0.10 is correctly the newer version.
• Treating the version as a decimal number. A version is not 1.10 the decimal. The dots separate independent integers, so minor 10 is ten releases after minor 9, not a smaller fraction.
• Assuming a prerelease outranks the release. A label like 1.0.0-rc.1 looks fuller and may feel later, but a prerelease always ranks below the matching final release 1.0.0. It is the version that comes before, not after.
• Expecting build metadata to break a tie. The part after a plus sign is build metadata and is ignored for precedence. 1.0.0+build.1 and 1.0.0+build.2 are equal in rank, so do not rely on it to order releases.
• Writing prerelease numbers with leading zeros. A numeric prerelease identifier may not have a leading zero, so 1.0.0-rc.01 is invalid. Use 1.0.0-rc.1 instead, or treat it as an alphanumeric label.

Glossary

Semantic Versioning (semver)

A versioning scheme of the form MAJOR.MINOR.PATCH where each number signals the kind of change made.

Major

The first number, bumped when a release introduces backward-incompatible (breaking) changes.

Minor

The second number, bumped when new backward-compatible features are added.

Patch

The third number, bumped for backward-compatible bug fixes only.

Prerelease

An optional label after a hyphen (such as -alpha or -rc.1) marking an unstable build that ranks below the final release.

Build metadata

An optional label after a plus sign (such as +20130313). It is recorded but ignored when comparing precedence.

Precedence

The order semver defines for two versions, deciding which one is newer or whether they rank equally.

Frequently asked questions