Semantic Versioning Calculator — Parse, Compare & Increment
Semantic Versioning (semver) is the standard versioning scheme used by npm, PyPI, Cargo, and virtually every modern package ecosystem. A version string takes the form MAJOR.MINOR.PATCH, with optional pre-release tags (e.g. -alpha.1, -rc.2) and build metadata (e.g. +sha.abc1234). This tool lets you parse, validate, compare, and auto-increment semver strings without memorizing the spec.
Increment MAJOR for breaking changes, MINOR for new features, PATCH for bug fixes. Pre-release precedence: alpha < beta < rc < release.
How Version Comparison Works
Semver comparison proceeds left to right. Given two versions, the tool first compares MAJOR numerically. If equal, it compares MINOR, then PATCH. If numeric parts are equal, a version without a pre-release tag wins (1.0.0 > 1.0.0-rc.1). Within pre-release identifiers, numeric segments are compared as integers and alphanumeric segments are compared lexicographically. Build metadata after + is always stripped before comparison.
npm Range Operators: ~ vs ^
The two most common npm range operators confuse even experienced developers. Tilde (~1.2.3) pins the MINOR version and allows only PATCH updates: it resolves to >=1.2.3 <1.3.0. Caret (^1.2.3) pins the MAJOR version and allows MINOR and PATCH updates: it resolves to >=1.2.3 <2.0.0. For packages with unstable minor releases, prefer tilde. For well-maintained packages that follow semver strictly, caret gives more flexibility.
When to Bump Each Version Component
The decision rule is simple: PATCH for any backward-compatible bug fix (no new API surface). MINOR for any new backward-compatible feature — existing code continues to work. MAJOR for any breaking change — removing a function, changing a signature, altering output format, or dropping a dependency your users relied on. When in doubt, bump MAJOR; under-bumping breaks consumer projects silently.
0.x Versions and Initial Development
Versions below 1.0.0 are a special contract: the public API is unstable and anything can change at any time. Breaking changes are allowed in MINOR bumps during 0.x development. Once you publish 1.0.0 you commit to the full semver contract. Many open-source projects stay at 0.x deliberately until they are confident in their API design.
Quick Reference
- MAJOR: breaking API changes — consumers must update their code
- MINOR: new features that don't break existing code
- PATCH: bug fixes with no API change
- Pre-release: -alpha < -beta < -rc < release
- Build metadata (+sha, +build) is ignored in precedence comparisons
- 0.x.x = unstable; 1.0.0+ = public stable API contract
Frequently Asked Questions
What is Semantic Versioning?
Semantic Versioning (semver) is a versioning scheme defined at semver.org. A version takes the form MAJOR.MINOR.PATCH, where MAJOR increments on breaking API changes, MINOR on backward-compatible new features, and PATCH on backward-compatible bug fixes.
When should I bump the major version?
Bump MAJOR when you make incompatible API changes that break existing consumers. For example, removing a public function, changing a function signature, or altering the output format of an endpoint all warrant a MAJOR bump. Version 1.0.0 signals the first stable public API.
What is a pre-release version in semver?
A pre-release version is denoted by appending a hyphen and identifiers after the PATCH number, e.g. 1.0.0-alpha.1 or 2.3.0-rc.2. Pre-release versions have lower precedence than the associated normal version. They signal software that is not yet ready for production.
How do I compare two version strings?
Semver comparison is done left to right: first compare MAJOR, then MINOR, then PATCH numerically. If those are equal, a version without a pre-release tag is greater than one with one (e.g. 1.0.0 > 1.0.0-rc.1). Build metadata (after +) is ignored in comparisons.
What is the difference between ~1.2.3 and ^1.2.3 in npm?
The tilde ~1.2.3 allows only PATCH-level changes: it matches >=1.2.3 <1.3.0. The caret ^1.2.3 allows MINOR and PATCH changes: it matches >=1.2.3 <2.0.0. Use ^ for most dependencies; use ~ when a library is known to introduce breaking changes in minor versions.
What does 0.x.x mean for stability?
Versions below 1.0.0 are considered initial development. Anything may change at any time, and the public API should not be considered stable. Breaking changes are allowed in MINOR bumps during 0.x development, which is why many projects stay at 0.x until their API solidifies.
What is build metadata in semver?
Build metadata is appended after a plus sign, e.g. 1.0.0+20231015.sha.abc1234. It conveys extra information like a build timestamp or commit hash. Build metadata is ignored when determining version precedence — two versions differing only in build metadata are considered equal.
Can a pre-release version be published to npm?
Yes. Use npm publish --tag beta (or alpha, rc, etc.) to publish a pre-release without it becoming the default @latest tag. Consumers must explicitly install it with npm install package@beta, protecting users who rely on the stable channel.