Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 36 ยท Installing and Versions

Version Ranges: Caret, Tilde and More

Learn how caret (^), tilde (~), comparison, x-range, hyphen and OR ranges select versions in package.json, with a runnable range matcher and examples for 0.x versions and pre-releases.

In package.json you rarely write one exact version. You write a range: a rule describing which versions are acceptable. When you install, the package manager picks the newest version inside every range involved. Ranges give you automatic bug fixes without surprise breaking changes, if you understand them.

The common range forms

Range Meaning Matches (example)
1.2.3 exactly this version only 1.2.3
^1.2.3 compatible: same MAJOR, at least 1.2.3 1.2.3 up to below 2.0.0
~1.2.3 patch updates only 1.2.3 up to below 1.3.0
>=1.2.0 <2.0.0 explicit comparison 1.2.0 up to below 2.0.0
1.x or 1.* any 1.minor.patch 1.0.0 up to below 2.0.0
1.2.x any patch of 1.2 1.2.0 up to below 1.3.0
1.2.0 - 1.4.0 hyphen range (inclusive) 1.2.0 through 1.4.0
^1.0.0 || ^2.0.0 either range any 1.x or 2.x
* or latest anything / the latest tag newest

Caret ^ is the default that npm install writes. It allows changes that do not modify the left-most non-zero number:

  • ^1.2.3 accepts >=1.2.3 <2.0.0.
  • ^0.2.3 accepts >=0.2.3 <0.3.0 (for 0.x, the minor acts as the major).
  • ^0.0.3 accepts only 0.0.3 and nothing higher below 0.0.4.

Tilde ~ is stricter: ~1.2.3 accepts >=1.2.3 <1.3.0. (~1 means >=1.0.0 <2.0.0.)

A range matcher you can run

This stand-in handles caret, tilde, exact, comparison sets, x-ranges, hyphen ranges and ||. It is not the real semver package, but it follows the same rules for these forms.

Node.js Range matcher (stand-in for the semver package)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Look at the ^0.2.3 row: it stops before 0.3.0. That is why 0.x packages feel "stricter" under caret.

Choosing a range style

  • Applications (things you deploy): the lockfile pins exact versions anyway, so caret ranges are fine. Many teams add --save-exact for important dependencies.
  • Libraries (things others install): use wide ranges for your dependencies so consumers can dedupe, and especially wide for peerDependencies (>=18 or ^18 || ^19).
  • Tooling where updates have bitten you: pin exactly or use tilde.

Setting the default prefix: npm config set save-prefix="~" makes installs write tildes; npm config set save-exact true writes exact versions.

Tags, URLs and local paths

A dependency value can also be a dist-tag ("latest", "next"), a git URL ("github:user/repo#v1.2.3"), a tarball URL, or a local path ("file:../shared"). All three managers add their own protocols for monorepos: workspace:* in pnpm and Yarn, covered in Workspaces. Avoid latest in real projects; each install could pick up a different major version.

Pre-releases and ranges

A range such as ^2.0.0 will not install 2.1.0-beta.1, even though it is numerically between. To opt in, name a pre-release in the range itself, or install a tag (npm install pkg@next). This keeps unstable builds away from people who did not ask for them.

Node.js Why caret ranges ignore pre-releases

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Checking what a range allows in practice

On your own computer, npm view express versions --json lists candidates, and npm install express@"^4.18" follows the range. You can see the newest acceptable version without installing by running npm view express@"^4.18" version; it prints one line per matching version. Updates are the topic of the next lesson, Updating and Outdated Packages.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which versions does ^1.2.3 accept?

    Caret allows changes that do not bump the left-most non-zero number.
  2. 2. Which versions does ~1.2.3 accept?

    Tilde allows patch-level changes only.
  3. 3. What is the upper bound of ^0.2.3?

    For 0.x the minor number is treated like the major one.
  4. 4. Why avoid "latest" as a dependency version in real projects?

    latest moves over time, so builds are not reproducible.

Summary

  • Ranges in package.json describe acceptable versions; the manager picks the newest match.
  • ^ allows non-breaking changes (watch 0.x), ~ allows patches only.
  • Also: exact, comparison sets, x-ranges, hyphen ranges and ||.
  • Plain ranges skip pre-releases.
  • Libraries use wide ranges; applications rely on the lockfile.

Next: Updating and Outdated Packages