What a Version Range Actually Allows
A dependency range is shorthand for a set of comparators. The caret allows changes that do not modify the leftmost non-zero part, so ^1.2.3 permits anything below 2.0.0, while ^0.2.3 only permits anything below 0.3.0 and ^0.0.3 permits nothing above 0.0.3. The tilde allows patch-level changes when a minor is given. Ranges can be combined with spaces for AND and || for OR, and a hyphen forms an inclusive span. This tool expands the shorthand and evaluates real versions against it using the SemVer 2.0.0 precedence rules, including the rule that a prerelease sorts below the release it precedes.
How to Test a Range
- 1Enter the range exactly as it appears in package.json, or pick one of the shorthand presets.
- 2Read the expanded comparators to see the real lower and upper bounds the shorthand produces.
- 3List the versions you care about, one per line, such as the versions a registry actually publishes.
- 4Check each result row to see which versions satisfy the range and which do not.
- 5Turn on prerelease inclusion if you intentionally install beta or release-candidate builds.
When Ranges Cause Confusion
Understand a caret on a 0.x package
Confirm that ^0.2.3 will not pick up 0.3.0, which is the single most misunderstood rule in npm ranges.
Predict what an install will resolve
Paste the published version list and see which one a fresh install would choose.
Explain an unexpected upgrade
Check whether a range genuinely allowed the version that broke a build, before blaming the lockfile.
Decide whether a beta is reachable
See that prereleases stay excluded unless the range names that exact version tuple or you opt in.
Frequently asked questions
Why does ^0.2.3 behave differently from ^1.2.3?
The caret allows changes that do not modify the leftmost non-zero element. For 1.2.3 that element is the major, so anything below 2.0.0 is allowed. For 0.2.3 it is the minor, so the range stops at 0.3.0. For 0.0.3 it is the patch, so only that exact patch is allowed. This treats pre-1.0 minors as breaking, which is the convention in that ecosystem.
Why is 2.0.0-beta.1 excluded from ^2.0.0?
Two reasons combine. A prerelease sorts below the release it precedes, so 2.0.0-beta.1 is not greater than or equal to 2.0.0. Separately, npm excludes prereleases from a range unless a comparator names that same major, minor and patch tuple, so betas do not appear in ordinary installs by accident.
Is build metadata considered?
No. SemVer states that build metadata after a plus sign is ignored for precedence, so 1.0.0+a and 1.0.0+b compare as equal. It is parsed and displayed but never affects whether a version satisfies a range.
Does this contact the npm registry?
No. You supply the version list yourself and all comparison happens locally, so the tool works offline and reveals nothing about the packages you are inspecting.