Quackyard
  • Loading…

Semver Range Checker

Check which versions satisfy an npm semver range, and read what the range means in plain words.

^1.2.3 means >=1.2.3 <2.0.0 — from 1.2.3 up to, but not including, 2.0.0

3 of 8 versions match — the newest is 1.9.9.

Each version · 8 versions
VersionFits the range
1.2.2
1.2.3
1.2.7
1.9.9
1.9.9-beta
2.0.0
2.0.0-rc.1
3.0.0

Follows node-semver, npm's range grammar: caret ^, tilde ~, x-ranges 1.2.x, hyphen ranges 1.2.3 - 2, || and comparators. A prerelease like 1.9.9-beta only matches when the range names a prerelease on the same 1.9.9 — that is why ^1.2.3 skips it. Everything runs in this page, nothing is uploaded.

Runs in your browser. Nothing you enter is sent anywhere.

How to use it

  1. Type a range into Range, or pick one of the example chips under it, such as ^1.2.3, ~1.2.3, 1.2.x or 1.2.3 - 2.
  2. Paste the versions to test into Versions, separated by spaces, commas or line breaks.

The result updates as you type, in your browser. The first line shows the range as plain comparators and in words: ^1.2.3 means >=1.2.3 <2.0.0, from 1.2.3 up to, but not including, 2.0.0. The next line counts the matches and names the highest one. The Each version table marks each token under Fits the range. A version written with a v or build metadata shows its normalized form in parentheses, and tokens that aren’t versions are listed after Not versions:.

Examples

The caret range ^1.2.3 against the page’s sample list:

1.2.2 1.2.3 1.2.7 1.9.9 1.9.9-beta 2.0.0 2.0.0-rc.1 3.0.0

The range reads >=1.2.3 <2.0.0. Three of the eight match, 1.2.3, 1.2.7 and 1.9.9, and the highest is 1.9.9. 1.9.9-beta sits inside the bounds but is a prerelease, so it’s skipped.

A caret range below 1.0.0, ^0.2.3, against 0.2.2 0.2.3 0.2.9 0.3.0 1.0.0:

>=0.2.3 <0.3.0

Only 0.2.3 and 0.2.9 match. The caret holds the leftmost non-zero part, here the minor version, fixed.

A prerelease in the range, ^1.2.3-beta.2, against 1.2.3-beta.1 1.2.3-beta.4 1.2.3 1.2.4-beta.1 1.5.0:

>=1.2.3-beta.2 <2.0.0

The matches are 1.2.3-beta.4, 1.2.3 and 1.5.0. 1.2.4-beta.1 is inside the bounds, but it’s a prerelease of 1.2.4, and the range only names a prerelease of 1.2.3.

A range written the Cargo or Python way, >=1.2.3, <2.0.0, is rejected with Invalid comparator: >=1.2.3,. npm separates comparators with a space, so >=1.2.3 <2.0.0 works.

Good to know

  • The range grammar is npm’s, and so is the engine. SemVer 2.0.0 defines versions and their order but no ranges; ^, ~, x and hyphen ranges come from node-semver, the library npm uses, and this page runs node-semver itself.
  • Caret keeps the leftmost non-zero number. ^1.2.3 is <2.0.0, ^0.2.3 is <0.3.0 and ^0.0.3 is <0.0.4. SemVer 2.0.0 says anything may change in a 0.y.z release, so a caret below 1.0.0 is cautious.
  • Tilde keeps the minor version. ~1.2.3 is <1.3.0. Given only a major, ~1 is >=1.0.0 <2.0.0, the same as ^1.
  • A prerelease has to be invited. A version like 2.0.0-rc.1 matches only when a comparator in the same || alternative names a prerelease of the same major.minor.patch. That’s why * skips it. node-semver’s includePrerelease option (-p on its command line) turns the rule off; this page always applies it.
  • The -0 you see elsewhere is the same bound. node-semver compiles ^1.2.3 to >=1.2.3 <2.0.0-0, where 2.0.0-0 is the lowest possible prerelease of 2.0.0. This page prints <2.0.0, as the npm docs do.
  • Partial versions round outward. In a hyphen range, 1.2.3 - 2.3 means <2.4.0, while a full 1.2.3 - 2.3.4 includes 2.3.4. >1.2 means >=1.3.0 and <=1.2 means <1.3.0. The hyphen needs a space on both sides: 1.2.3 -2.0.0 fails with Invalid comparator: -2.0.0.
  • An empty side of || means any version. 1.2.3 || reads as *.
  • Versions must be complete. SemVer 2.0.0 requires three numbers without leading zeros, so 1.2 and 1.02.3 are not versions. A leading v is accepted, as npm accepts it. Build metadata after + is ignored for matching, so 1.2.9+build.5 is tested as 1.2.9.
  • Prereleases sort by identifier. Numeric parts compare as numbers, so 1.0.0-beta.11 is above 1.0.0-beta.2, and any prerelease is below its release: 1.0.0-rc.1 comes before 1.0.0.
  • The range takes up to 200 characters and the list up to 1,000 versions; the table shows the first 300.

Questions

What is the difference between caret and tilde in npm?

A caret allows minor and patch updates, a tilde only patch updates: ^1.2.3 accepts 1.9.9 but not 2.0.0, and ~1.2.3 accepts 1.2.9 but not 1.3.0. Below 1.0.0 the caret narrows, so ^0.2.3 behaves like ~0.2.3. npm install writes a caret into package.json by default, set by the save-prefix option.

Why doesn’t my prerelease version match the range?

Because node-semver lets a prerelease through only when the range names a prerelease of the same major.minor.patch. >=1.2.3-beta.2 admits 1.2.3-beta.4 and every release above 1.2.3, but no 1.3.0-alpha.

What does 1.x or * mean in package.json?

1.x (also 1.* or just 1) means any 1.y.z release, >=1.0.0 <2.0.0, and * means any release at all. Neither matches prereleases, and both accept versions older than the one you tested with.

How do I check a semver range in code or the terminal?

In JavaScript, semver.satisfies('1.2.4', '^1.2.3') from the semver package returns true, and semver.maxSatisfying(versions, range) picks the highest match. In a shell, npx semver -r '^1.2.3' 1.2.4 2.0.0 prints the versions that match, here 1.2.4, and exits with status 1 when none does.

Common answers