Semantic Version Comparator

Compare, sort, increment, and range-test SemVer version numbers with visual diff highlighting.

Enter version numbers above.

How to Use the SemVer Comparator

  1. Compare — enter two version strings. The tool highlights which part (major, minor, patch, or pre-release) differs and shows the comparison result with an arrow.
  2. Sort — paste a list of versions, one per line. Toggle ascending or descending. Invalid entries are flagged.
  3. Increment — enter a current version and optionally a pre-release tag. The tool generates all valid next versions.
  4. Range — enter a version and a range expression (^1.2.3, ~1.2.3, >=1.0.0 <2.0.0). The tool tells you if the version satisfies the range.

Semantic Versioning Explained

Semantic Versioning (SemVer 2.0.0) is defined at semver.org. A version number has the form MAJOR.MINOR.PATCH, optionally followed by a pre-release identifier (-alpha.1) and build metadata (+build.20260322). The specification defines strict rules for when each component is incremented, ensuring that downstream consumers of a library can predict compatibility from the version number alone.

Version Comparison Rules

SemVer precedence is determined by comparing each component from left to right as integers. Build metadata is ignored when determining precedence. Pre-release versions have lower precedence than the associated normal version (1.0.0-rc.1 < 1.0.0). When comparing pre-release identifiers, numeric identifiers are compared numerically; alphanumeric identifiers are compared lexically in ASCII sort order; numeric identifiers always have lower precedence than alphanumeric identifiers (a numeric identifier is "smaller" than an alphanumeric one).

npm Range Syntax

npm uses a range syntax based on SemVer. The most common operators are:

  • ^1.2.3 — compatible with 1.2.3, matches >=1.2.3 <2.0.0
  • ~1.2.3 — approximately equivalent, matches >=1.2.3 <1.3.0
  • >=1.0.0 <2.0.0 — explicit range (space = AND, || = OR)
  • 1.x or 1.* — wildcard minor and patch, same as >=1.0.0 <2.0.0
  • * — matches any version

Ranges are used in package.json dependencies to allow automatic patch and minor updates while preventing unexpected major-version breaking changes. When running npm install, npm resolves the highest version in your range that is published on the registry.

When to Bump Each Component

MAJOR: Remove or rename a public API, change a function's behaviour incompatibly, or drop support for a platform/runtime that users depend on. MINOR: Add a new function, class, or endpoint that is fully backward-compatible — existing code still works unchanged. PATCH: Fix a bug without changing the public API. Security fixes, performance improvements, and documentation corrections are typically patch-level. If you are unsure, err on the side of a higher increment — it is always safe to over-increment but never safe to under-increment.

Pre-release Versions

Pre-release identifiers are added with a hyphen: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-rc.1. Identifiers composed entirely of digits are compared numerically; all other identifiers are compared as ASCII strings. A longer set of pre-release identifiers has higher precedence than a shorter set when all preceding identifiers are equal. See the CHANGELOG Builder for documenting pre-release notes.

Frequently Asked Questions

Semantic Versioning (SemVer) is a versioning scheme using three numbers: MAJOR.MINOR.PATCH. Increment MAJOR for breaking changes, MINOR for new backward-compatible features, and PATCH for backward-compatible bug fixes. Optional pre-release and build metadata can be appended.
The caret (^) allows changes that do not modify the left-most non-zero digit. So ^1.2.3 matches >=1.2.3 <2.0.0, ^0.2.3 matches >=0.2.3 <0.3.0, and ^0.0.3 matches only 0.0.3. It is the default range used by npm install.
The tilde (~) is more restrictive than the caret (^). ~1.2.3 matches >=1.2.3 <1.3.0 (patch-level changes only). ^1.2.3 matches >=1.2.3 <2.0.0 (minor and patch changes). Use ~ when you need tighter control over which patch versions are accepted.
Pre-release versions have lower precedence than the associated normal version. So 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0. Within pre-release identifiers, numeric fields are compared numerically, alphanumeric fields lexically.
Bump MAJOR when you make changes that break backward compatibility — removing or renaming public APIs, changing function signatures, altering data formats in incompatible ways, or dropping support for runtimes. If users must update their code to migrate, it is a major bump.