Semantic Versioning Reference
Reference semantic versioning parts, ranges, pre-release versions, build metadata, and common version bump rules.
SemVer format:
MAJOR for breaking changes.
MINOR for backward-compatible features.
PATCH for backward-compatible fixes.
MAJOR.MINOR.PATCH.
MAJOR for breaking changes.
MINOR for backward-compatible features.
PATCH for backward-compatible fixes.
SemVer Reference
| Item | Pattern | Meaning | When to Use | Example |
|---|---|---|---|---|
| MAJOR | 1.x.x |
Breaking changes | Increment when an update can break existing users or integrations. | 1.4.2 → 2.0.0 |
| MINOR | x.1.x |
Backward-compatible features | Increment when adding functionality without breaking existing behavior. | 1.4.2 → 1.5.0 |
| PATCH | x.x.1 |
Backward-compatible fixes | Increment when fixing bugs without adding features or breaking behavior. | 1.4.2 → 1.4.3 |
| Pre-release | 1.0.0-alpha.1 |
Unstable version before a stable release | Use for alpha, beta, rc, preview, or testing releases. | 1.0.0-beta.2 |
| Build metadata | 1.0.0+build.123 |
Extra build information | Use for build IDs, commit hashes, CI run IDs, or packaging metadata. | 1.0.0+20260514 |
| Caret range | ^1.2.3 |
Compatible updates | Allows updates that do not change the leftmost non-zero version segment. | ^1.2.3 allows 1.x.x, not 2.0.0 |
| Tilde range | ~1.2.3 |
Patch-level updates | Allows patch updates within the same minor version. | ~1.2.3 allows 1.2.x, not 1.3.0 |
| Exact version | 1.2.3 |
Only one version | Use when you need a specific fixed version. | 1.2.3 |
| Greater than | >1.2.3 |
Versions higher than a given version | Use when anything newer than a specific version is acceptable. | >1.2.3 |
| Greater than or equal | >=1.2.3 |
A version or anything newer | Use when a minimum version is required. | >=1.2.3 |
| Less than | <2.0.0 |
Versions lower than a given version | Use when you need to block a future breaking version. | <2.0.0 |
| Less than or equal | <=1.2.3 |
A version or anything older | Use when a maximum version is required. | <=1.2.3 |
| Range | >=1.2.0 <2.0.0 |
Versions inside a bounded range | Use when defining both a minimum and maximum allowed version. | >=1.2.0 <2.0.0 |
| Hyphen range | 1.2.3 - 2.3.4 |
Inclusive version range | Use for readable lower-to-upper version constraints. | 1.2.3 - 2.3.4 |
| Wildcard | 1.2.x |
Any matching version segment | Use when any patch version in a minor line is acceptable. | 1.2.x allows 1.2.0, 1.2.1, 1.2.99 |
| Star | * |
Any version | Use when no version restriction is needed. | * |
| Latest | latest |
Dist-tag or moving pointer to a version | Common in npm, but not a SemVer version itself. | npm install package@latest |
Bump Rules
| Change | Bump | Before | After | Note |
|---|---|---|---|---|
| Breaking API change | MAJOR | 1.4.2 |
2.0.0 |
Use when existing callers may need code changes. |
| Backward-compatible feature | MINOR | 1.4.2 |
1.5.0 |
Use when adding new behavior safely. |
| Backward-compatible bug fix | PATCH | 1.4.2 |
1.4.3 |
Use for fixes that preserve behavior. |
| Pre-release candidate | Pre-release | 1.5.0 |
1.5.0-rc.1 |
Use before publishing a stable release. |
| Build-only change | Build metadata | 1.5.0 |
1.5.0+build.1 |
Does not affect precedence. |