SemVer Range Calculator

Caret (^) allows changes that do not modify the leftmost non-zero element of the version. For ^1.2.3 it means >=1.2.3 <2.0.0 — minor and patch updates are allowed, but the major version is locked. For ^0.2.3 it means >=0.2.3 <0.3.0 — when major is 0, the minor version is treated as the major and only patches are allowed. For ^0.0.3 it means exactly =0.0.3. Tilde (~) is more conservative: ~1.2.3 means >=1.2.3 <1.3.0 — only patch updates are allowed within the same minor version. Use ~ when you want the most conservative updates; use ^ for typical library dependencies where you trust the author to maintain backward compatibility within a major version.

Pre-release versions (e.g. 2.0.0-alpha.1, 1.0.0-beta.2, 3.0.0-rc.1) are treated as lower than the release version they precede. So 2.0.0-alpha.1 < 2.0.0. By default, ranges like ^1.2.3 and >=1.0.0 do NOT match pre-release versions of a different major.minor.patch unless the range itself includes a pre-release tag. For example, >=1.0.0-alpha will match 1.0.0-alpha.1, but >=1.0.0 will NOT match 1.0.0-alpha.1. This protects users from accidentally getting unstable pre-release versions when updating.

npm install (fresh) resolves the range to the highest matching version at install time and writes the exact version to package-lock.json. Subsequent npm install commands use the lockfile and install that exact version — your range is only consulted when there is no lockfile. npm update (or npm update package-name) re-resolves the range and installs the highest matching version, updating the lockfile. npm outdated shows you the current, wanted (highest matching your range), and latest (absolute latest) versions. The range in package.json defines the update boundary; the lockfile pins the exact resolved version.

Semantic Versioning (SemVer) is a versioning scheme specified at semver.org. A version has the format MAJOR.MINOR.PATCH where MAJOR increments indicate breaking changes, MINOR increments indicate backward-compatible new features, and PATCH increments indicate backward-compatible bug fixes. Pre-release versions are denoted with a hyphen (1.0.0-alpha.1) and build metadata with a plus sign (1.0.0+build.123). The specification was created by Tom Preston-Werner (GitHub co-founder). npm, Cargo, Composer, and most package managers follow SemVer conventions, though the exact range syntax varies between ecosystems — Cargo and npm have slightly different caret range semantics for 0.x versions.

Lock files (package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.lock) record the exact resolved version of every dependency (and transitive dependency) at a specific point in time. Without a lock file, the same package.json could install different versions on different machines or at different times — a new patch released between your CI run and a teammate's install could cause different behavior. Lock files give you reproducible builds. The version range in package.json defines the upgrade boundary (what you're willing to accept), while the lock file ensures everyone runs the same exact versions. Commit lock files for applications; for libraries, omit them so consumers get the latest compatible versions.

MAJOR (e.g. 2.0.0): You made breaking changes — renamed/removed APIs, changed function signatures, dropped support for older Node/Python versions. Dependents MUST update their code to keep working. MINOR (e.g. 1.3.0): You added new functionality in a backward-compatible way — new functions, new optional parameters, new exports. Dependents can upgrade safely without changing their code, though they might want to use the new features. PATCH (e.g. 1.2.4): Bug fixes only — no new features, no API changes. Always safe to upgrade. In practice, many projects bump MAJOR for any significant change even if technically compatible, while others underuse MAJOR and make breaking changes in MINOR — always read the CHANGELOG before upgrading.