Semver Version Range Viewer

Semantic Versioning (Semver)

semver, short for Semantic Versioning, is a versioning convention documented at semver.org. A version number consists of three parts: [major, minor, patch], where:

• major: incremented when you make incompatible API changes (Breaking Changes)
• minor: incremented when you add functionality in a backward-compatible manner
• patch: incremented when you make backward-compatible bug fixes

For ~1.2.3, the matched version range is >=1.2.3 <1.3.0

For ^1.2.3, the matched version range is >=1.2.3 <2.0.0

npm packages use semver for version management. When you install lodash and the latest version is lodash@4.17.4, npm will save lodash@^4.17.4 in your package.json by default.

Enter a Version Range

Type a semver range expression into the input field, and the tool will parse and display the matching version interval. Common range syntax includes:

• ^1.2.3: allows patch and minor updates, matches >=1.2.3 <2.0.0
• ~1.2.3: allows patch updates only, matches >=1.2.3 <1.3.0
• >=1.0.0: greater than or equal to the specified version
• 1.0.0 - 2.0.0: a closed range
• >=1.0.0 <2.0.0: combined conditions — a space means "AND"
• ^1.0.0 || ^2.0.0: use || for "OR" — matches if either range is satisfied

Check Whether a Version Satisfies a Range

Enter a specific version number and a range expression, and the tool will tell you whether the version falls within the range. This is especially useful when troubleshooting dependency conflicts — you can quickly verify whether a package's actual version satisfies the constraint declared in package.json.

Understanding Version Comparison

The tool displays the relationship between two versions in a clear, visual way. A version number has three components:

• Major: incremented for incompatible API changes
• Minor: incremented for new backward-compatible features
• Patch: incremented for backward-compatible bug fixes

Pre-release tags (e.g., 1.0.0-beta.1) have lower precedence than the corresponding release version.

Real-World Scenarios

package.json Dependency Declarations

{
  "dependencies": {
    "react": "^18.2.0",
    "lodash": "~4.17.21",
    "typescript": ">=5.0.0 <6.0.0"
  }
}

• ^18.2.0 is npm's default behavior — it allows any 18.x.x version but won't jump to 19.0.0
• ~4.17.21 is more conservative, accepting only 4.17.x patch updates
• >=5.0.0 <6.0.0 explicitly spells out the range — equivalent to ^5.0.0 but more explicit

Troubleshooting Dependency Conflicts

When npm install reports a version conflict, paste the version numbers and ranges from the error message into the tool to quickly see which ranges are incompatible, helping you decide whether to upgrade a dependency or adjust a range.

Pre-Release Verification

Before publishing a new version, you can use the tool to verify whether the new version number falls within downstream projects' dependency ranges. For example, if you plan to publish 2.0.0 but a downstream project has ^1.5.0, that release won't be picked up automatically — you'll need to notify them in advance.

API

JavaScript

$ npm install semver

import { Range } from 'semver'

// >=1.2.3 <2.0.0-0
new Range('^1.2.3').range

FAQ

Q: What is the difference between ^ and ~?

^ (caret) allows updates without modifying the leftmost non-zero version number. For example, ^1.2.3 matches >=1.2.3 <2.0.0, allowing both minor and patch updates. ~ (tilde) is more conservative, only allowing patch-level updates. For example, ~1.2.3 matches >=1.2.3 <1.3.0, accepting only patch version changes. In short, ^ trusts that the library author follows semver conventions (new features are backward-compatible), while ~ only accepts bug fixes.

Q: Why does npm default to ^ instead of exact versions?

npm defaults to ^ to strike a balance between stability and flexibility. While locking to exact versions is the safest approach, it leads to excessive duplicate packages in the dependency tree, inflates node_modules size, and prevents you from automatically receiving security patches. The ^ prefix allows automatic backward-compatible updates, including bug fixes and new features, while package-lock.json ensures version consistency across team members. This strategy assumes library authors follow semver conventions and won't introduce breaking changes in minor versions.

Q: Does ^ behave differently with 0.x.x versions?

Yes, this is a common pitfall in semver. With 0.x.x versions, ^ behaves differently: ^0.2.3 matches >=0.2.3 <0.3.0, effectively the same as ~0.2.3, because 0.x is considered an unstable development phase where any minor change may include breaking modifications. Even more restrictive, ^0.0.3 matches only 0.0.3 itself. This means that when using 0.x libraries, ^ is not as permissive as it is with 1.x and above — you need to pay special attention.

Q: How can I lock dependency versions?

There are several ways to lock versions. The simplest approach is to write an exact version number in package.json, such as "lodash": "4.17.21", without any prefix. You can also use npm install --save-exact or set save-exact=true in .npmrc to default to exact versions. Additionally, package-lock.json (npm) or pnpm-lock.yaml (pnpm) records the exact versions actually installed, ensuring CI/CD and team members use identical dependency versions. It's recommended to commit lock files to version control.

Q: How are pre-release versions (e.g., 1.0.0-beta.1) compared?

Pre-release versions have lower precedence than the corresponding release version. For example, 1.0.0-alpha.1 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0. Pre-release identifiers are compared left-to-right, segment by segment: numeric segments are compared as integers, string segments are compared lexicographically, and numeric segments have lower precedence than string segments. Note that in range expressions, ^1.0.0 and ~1.0.0 do not match pre-release versions like 1.1.0-beta.1 by default — only pre-releases with the same major.minor.patch as specified in the range will be included.