Semantic Versioning: Parse, Compare, and Increment Version Strings
Semantic Versioning (semver) is a formal specification for version numbers used by npm, Cargo, pip, and most modern package ecosystems. A version string follows the pattern MAJOR.MINOR.PATCH, where each part has a defined meaning: MAJOR breaks backward compatibility, MINOR adds features without breaking changes, and PATCH fixes bugs. Understanding semver helps you choose the right version bumps, write correct dependency ranges, and avoid breaking your users' builds.
Per semver.org spec. Pre-release versions (1.0.0-alpha.1) have lower precedence than the release. Build metadata (+20230101) is ignored in comparisons.
The Three Version Numbers — When to Bump Each
MAJOR: Increment when you make incompatible API changes. Consumers must update their code. Reset MINOR and PATCH to 0. MINOR: Increment when you add functionality in a backward-compatible way. Reset PATCH to 0. PATCH: Increment for backward-compatible bug fixes only. If you are at 0.x.x, APIs are considered unstable and breaking changes are allowed in minor releases.
Pre-Release and Build Metadata
Append a hyphen and dot-separated identifiers for pre-release versions: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-rc.3. Pre-release versions have lower precedence than the associated release (1.0.0-alpha < 1.0.0). Build metadata (appended with +) is informational only and ignored in version comparisons.
npm Range Syntax: ^ and ~ Explained
Caret (^): Compatible releases. ^1.2.3 means >=1.2.3 <2.0.0 — allows MINOR and PATCH bumps. ^0.2.3 means >=0.2.3 <0.3.0 — more conservative for unstable APIs. Tilde (~): Patch-level changes only. ~1.2.3 means >=1.2.3 <1.3.0. Use tilde when you want only bug fixes and no new features. Use caret (the npm default) when you trust backward-compatibility.
When to Bump Each Version
- MAJOR: breaking API change — rename/remove a function, change a return type
- MINOR: new feature, backward-compatible — add a new endpoint or parameter
- PATCH: bug fix — fix incorrect behavior without changing the API
- 0.x.x: API is unstable; breaking changes may occur in minor releases
npm Range Operator Reference
- ^1.2.3 — compatible: >=1.2.3 <2.0.0 (default npm install behavior)
- ~1.2.3 — patch only: >=1.2.3 <1.3.0
- >=1.2.3 — any version at or above 1.2.3
- * or x — any version (dangerous for production deps)
- 1.2.x — any patch of 1.2
Frequently Asked Questions
What is Semantic Versioning?
Semantic Versioning (semver) is a formal specification (semver.org) for version numbers in the format MAJOR.MINOR.PATCH. Each component has a defined meaning: MAJOR for breaking changes, MINOR for new backward-compatible features, and PATCH for bug fixes.
When should I bump the major version?
Bump MAJOR when you make incompatible API changes — removing or renaming a public function, changing a parameter type, or altering behavior in a way that breaks existing consumers. Also reset MINOR and PATCH to 0. Exception: 0.x.x versions are considered unstable and breaking changes are allowed in minor releases.
What is the difference between ^1.2.3 and ~1.2.3 in npm?
^1.2.3 (caret) allows MINOR and PATCH updates: >=1.2.3 <2.0.0. It is npm's default when you run npm install. ~1.2.3 (tilde) allows only PATCH updates: >=1.2.3 <1.3.0. Use tilde when you want to limit updates to bug fixes only and avoid new features.
What does 0.x.x mean for API stability?
Per semver spec, versions below 1.0.0 are for initial development. Anything may change at any time — the public API is not considered stable. A minor version bump (0.1.0 → 0.2.0) may include breaking changes. Consumers should pin to an exact version or tight range for 0.x packages.
What is a pre-release version?
Pre-release versions append a hyphen and identifiers after the PATCH number: 1.0.0-alpha, 1.0.0-beta.2, 1.0.0-rc.1. They have lower precedence than the release version (1.0.0-alpha < 1.0.0). Use them to signal that a version is not yet ready for production use.
How do I compare two version strings?
Compare numerically left to right: MAJOR first, then MINOR, then PATCH. If all three are equal, a version without a pre-release tag is greater than one with (1.0.0 > 1.0.0-rc.1). Pre-release identifiers are compared lexicographically for non-numeric parts and numerically for numeric parts.
Should I use semver for internal tools and private packages?
Yes — semver's value is in communicating intent to consumers, even internal ones. It helps teammates understand whether a library update requires code changes (MAJOR bump) or is safe to upgrade automatically (PATCH bump). Most private npm registries and monorepo tools (Lerna, Nx) rely on semver for automated release management.