npm Version Range Cheat Sheet — All Operators Explained

npm Version Range Cheat Sheet

A complete quick-reference for every range operator supported in package.json.

Operators at a Glance

Operator	Syntax	Example	Expands To
Caret	^A.B.C	^1.2.3	>=1.2.3 <2.0.0
Tilde	~A.B.C	~1.2.3	>=1.2.3 <1.3.0
Exact	A.B.C	1.2.3	=1.2.3
Greater/Equal	>=A.B.C	>=1.2.3	Version 1.2.3 or higher
Less Than	<A.B.C	<2.0.0	Below version 2.0.0
Hyphen	A - B	1.0.0 - 2.0.0	>=1.0.0 <=2.0.0
Wildcard	A.x	1.x	>=1.0.0 <2.0.0
OR	A || B	^1.0.0 || ^2.0.0	Either range

Caret (^) — The Default

The caret is the default operator added by npm install. It allows changes that do not modify the left-most non-zero digit:

^1.2.3  →  >=1.2.3 <2.0.0   (minor + patch updates)
^0.2.3  →  >=0.2.3 <0.3.0   (patch updates only)
^0.0.3  →  >=0.0.3 <0.0.4   (exact match)

Tilde (~) — Conservative

Allows only patch-level changes:

~1.2.3  →  >=1.2.3 <1.3.0
~0.2.3  →  >=0.2.3 <0.3.0

Comparison Operators

Combine for custom ranges:

>=1.0.0 <2.0.0        same as ^1.0.0
>=1.2.0 <1.3.0        same as ~1.2.0
>1.0.0 <=2.0.0        excludes 1.0.0, includes 2.0.0

OR Unions (||)

Match any of the listed ranges:

^16.8.0 || ^17.0.0 || ^18.0.0
>=1.0.0 <1.5.0 || >=2.0.0

Wildcards

x, *, or missing parts mean "any":

*        →  >=0.0.0     (any version)
1.x      →  >=1.0.0 <2.0.0
1.2.x    →  >=1.2.0 <1.3.0

Hyphen Ranges

1.0.0 - 2.0.0  →  >=1.0.0 <=2.0.0
1.0 - 2.0      →  >=1.0.0 <2.1.0  (partial high fills up)

Decision Flowchart

1. Want latest patches + features? → ^1.2.3 (caret)
2. Want only bug fixes? → ~1.2.3 (tilde)
3. Need exact version? → 1.2.3 (no operator)
4. Support multiple majors? → ^1.0.0 || ^2.0.0 (OR)
5. Custom bounds? → >=1.0.0 <3.0.0 (comparison)