How to use the semver calculator
- Pick a mode: range checker, compare, bump, sort or pick.
- Enter the version and, for the range modes, an npm range such as
^1.2.3or1.x || >=3. - For compare, add the second version. For bump, choose the bump type and an optional prerelease identifier. For sort and pick, paste the list.
- Read the result rows, including the normalized range and any prerelease note.
How npm decides whether a version satisfies a range
A semantic version has three numbers, MAJOR.MINOR.PATCH, optionally followed by a prerelease tag after a hyphen (2.0.0-beta.1) and build metadata after a plus sign (2.0.0+20260101). A range is one or more comparators. Space-separated comparators must all match, and groups separated by || match if any group does. This semver range checker applies the same rules as the npm semver package, so the answer matches what npm install resolves.
For example, does 1.9.4 satisfy ^1.2.3? The caret expands to >=1.2.3 <2.0.0-0, and 1.9.4 is above the lower bound and below the upper one, so yes. Does 2.0.0 satisfy it? No, it equals the upper bound, which is excluded.
Caret, tilde, x-ranges and hyphen ranges
Shorthand ranges are rewritten into plain comparators before matching. The table shows what each common form becomes.
| Range you write | What npm expands it to |
|---|---|
^1.2.3 | >=1.2.3 <2.0.0-0 |
^0.2.3 | >=0.2.3 <0.3.0-0 |
^0.0.3 | >=0.0.3 <0.0.4-0 |
~1.2.3 | >=1.2.3 <1.3.0-0 |
~1.2 | >=1.2.0 <1.3.0-0 |
1.x | >=1.0.0 <2.0.0-0 |
>=1.2.3 <2.0.0 | >=1.2.3 <2.0.0 |
1.2.3 - 2.3.4 | >=1.2.3 <=2.3.4 |
* | * |
The caret keeps the left-most non-zero number fixed, which is why ^0.2.3 stays within 0.2.x and ^0.0.3 allows only 0.0.3. The tilde allows patch updates only when a minor version is given, so ~1.2.3 stays within 1.2.x. A hyphen range is inclusive at both ends, and a partial upper bound such as - 2.3 means anything below 2.4.0.
Prerelease rules that surprise people
A prerelease version only matches a range when some comparator in the same group names a prerelease of the exact same MAJOR.MINOR.PATCH. That is why 2.0.0-beta.3 does not satisfy >=1.0.0 <3.0.0 even though the numbers fit, and why 1.2.4-beta.1 does not satisfy ^1.2.3. By contrast 1.2.3-beta.2 does satisfy ^1.2.3-beta.1, because the range itself mentions a 1.2.3 prerelease.
When this happens the semantic version calculator adds a note explaining that the prerelease rule, not the numbers, caused the miss. Precedence among prereleases follows the spec: numeric identifiers compare as numbers, text identifiers compare alphabetically, numbers rank below text, and a longer list of identifiers wins over a shorter one with the same start. So 1.0.0-alpha.2 is lower than 1.0.0-alpha.10, and every prerelease is lower than the release it leads to.
Comparing and sorting versions
Version strings do not sort alphabetically. Plain text order puts 1.10.0 before 1.9.0, which is wrong. Compare mode returns -1, 0 or 1 using real precedence and also reports the kind of difference: major, minor, patch, prerelease, or the pre variants such as premajor. Build metadata is ignored, so 2.1.0+b1 and 2.1.0+b2 are equal.
Sort mode orders a pasted list from lowest to highest and drops entries that are not valid versions, listing them so you can fix them. Pick mode takes the same list plus a range and returns the highest and lowest match, the same result as maxSatisfying and minSatisfying in the npm package. It is handy for answering "which version would npm install from this list?".
Bumping a version: major, minor, patch and prerelease
Bump mode follows semver.inc. A patch bump on 1.2.3 gives 1.2.4, a minor bump gives 1.3.0, and a major bump gives 2.0.0, with lower numbers reset to zero. If the version is already a prerelease, the bump can simply finish it: bumping 1.2.3-beta.1 by patch gives 1.2.3, because the release was still pending.
- prerelease on 1.2.3 with the identifier beta gives 1.2.4-beta.0. On 1.2.3-beta.1 it gives 1.2.3-beta.2.
- premajor with rc on 1.2.3 gives 2.0.0-rc.0.
- preminor with alpha on 1.2.0 gives 1.3.0-alpha.0.
- prepatch without an identifier gives 1.2.4-0.
Use this when you plan a release by hand or write a changelog and want the next number to be right.
Common mistakes with npm version ranges
- Leading zeros are invalid:
01.2.3is rejected, as in npm. - A partial version is not a version.
1.2is fine as a range but not as the version you test. - Writing
>1.2 <2allows 1.3.0 and up but not 1.2.5, because>1.2means at least 1.3.0. - A caret on a
0.xversion is much narrower than on 1.x and above. - Ranges are case-sensitive for the prerelease text but not for x, so
1.Xand1.xare the same.
Worked examples
| Example | Input | Result |
|---|---|---|
| Caret range includes minor updates | Mode: satisfies; Version: 1.9.4; npm range: ^1.2.3; Second version (compare mode): 1.2.0; Bump type: patch; List of versions (sort and pick modes): 1.0.0 / 1.2.0 / 2.0.0 | Result: Yes, 1.9.4 satisfies ^1.2.3; Version (normalized): 1.9.4; Range (normalized): >=1.2.3 <2.0.0-0 |
| Prerelease skipped by a plain range | Mode: satisfies; Version: 2.0.0-beta.3; npm range: >=1.0.0 <3.0.0; Second version (compare mode): 1.2.0; Bump type: patch; List of versions (sort and pick modes): 1.0.0 / 1.2.0 / 2.0.0 | Result: No, 2.0.0-beta.3 does not satisfy >=1.0.0 <3.0.0; Version (normalized): 2.0.0-beta.3; Range (normalized): >=1.0.0 <3.0.0 |
| Compare release vs release candidate | Mode: compare; Version: 3.0.0; npm range: ^1.0.0; Second version (compare mode): 3.0.0-rc.2; Bump type: patch; List of versions (sort and pick modes): 1.0.0 / 1.2.0 / 2.0.0 | Comparison: 3.0.0 is greater than 3.0.0-rc.2; compare(): 1; Difference: major; Newer version: 3.0.0 |
| Start a beta line | Mode: bump; Version: 1.4.2; npm range: ^1.0.0; Second version (compare mode): 1.2.0; Bump type: preminor; Prerelease identifier (optional): beta; List of versions (sort and pick modes): 1.0.0 / 1.2.0 / 2.0.0 | New version: 1.5.0-beta.0; Old version: 1.4.2; Bump: preminor with identifier beta |
| Sort a messy list | Mode: sort; Version: 1.2.3; npm range: ^1.0.0; Second version (compare mode): 1.2.0; Bump type: patch; List of versions (sort and pick modes): 1.10.0 1.2.0 1.2.0-rc.1 0.9.0 | Lowest: 0.9.0; Highest: 1.10.0; Valid versions: 4 |
| Pick the best install | Mode: pick; Version: 1.2.3; npm range: ~1.4.0 || ^2.0.0; Second version (compare mode): 1.2.0; Bump type: patch; List of versions (sort and pick modes): 1.0.0 1.4.2 1.9.0 2.0.0 | Highest match: 2.0.0; Lowest match: 1.4.2; Matching versions: 2 of 4; Range (normalized): >=1.4.0 <1.5.0-0||>=2.0.0 <3.0.0-0 |
FAQ
What is an npm semver calculator?
It is a tool that applies npm's semantic versioning rules: it checks whether a version satisfies a range, compares two versions, sorts a list, and bumps a version number, all without installing anything.
How do I use this as a semver range checker?
Choose the range checker mode, type a version such as 1.9.4 and a range such as ^1.2.3, and read the result. The normalized range row shows exactly which comparators npm uses.
Why does 1.2.4-beta.1 not satisfy ^1.2.3?
npm skips prereleases unless the range names a prerelease of the same major, minor and patch. Use a range like ^1.2.4-beta.0 or test the final 1.2.4 release instead.
What is the difference between ^ and ~?
The caret allows changes that do not modify the left-most non-zero number, so ^1.2.3 means below 2.0.0. The tilde allows patch changes when a minor is given, so ~1.2.3 means below 1.3.0.
Does the semantic version calculator support build metadata?
Yes. The part after the plus sign is accepted but never affects precedence, so 1.0.0+a and 1.0.0+b compare as equal.
Is my version data sent anywhere?
No. Everything runs in your browser, so the versions and ranges you type stay on your device.