Master npm Dependency Versioning: Caret (^), Tilde (~) and Range Syntax Explained

1. Introduction

To illustrate the concepts we use

lodash

, one of the most depended‑upon modules. The tests were run on Windows 7 64‑bit with npm

v3.8.1

; results may differ on other platforms or npm versions.

Running

npm install lodash --save

creates a

package.json

that looks like:

<code>{
  "name": "test",
  "dependencies": {
    "lodash": "^4.11.1"
  }
}</code>

The

^4.11.1

part is the focus: the leading

^

(caret) and other notations such as

~4.11.1

,

<4.11.1

have distinct meanings.

2. Semantic Versioning

Before diving in, understand Semantic Versioning (SemVer) v2.0.0, which uses the format

MAJOR.MINOR.PATCH

. The rules are:

MAJOR: incremented for incompatible API changes.

MINOR: incremented for backward‑compatible feature additions.

PATCH: incremented for backward‑compatible bug fixes.

3. Version Specifier Syntax

When configuring

dependencies

in

package.json

, several specifier styles are available.

3.1 Caret (^) and Tilde (~)

The caret

^

and tilde

~

are the most common and often confusing. They can be used directly in

package.json

or via commands such as

npm install lodash@^3.3.0

and

npm install lodash@~3.3.0

.

3.1.1 Meaning and Comparison

^4.11.1

: Compatible with 4.11.1, range

4.11.1 ≤ version < 5.0.0

(major version unchanged).

~4.11.1

: Reasonably close to 4.11.1, range

4.11.1 ≤ version < 4.12.0

(major and minor unchanged).

It is hard to translate these precisely; consult a dictionary if needed.

Using

^

is more aggressive—it fetches the newest compatible version—while

~

is more conservative, staying close to the specified version.

Both keep the major version fixed because a change would break API compatibility.

The minimum version is always ≥ the specified one; an error is thrown if no version satisfies the range.

3.1.2 Exception for 0.x.x Versions

Versions starting with

0

are considered unstable; any change may occur. In this range,

^

behaves like

~

. For example,

^0.3.0

and

~0.3.0

both resolve to

0.3.0 ≤ version < 0.4.0

.

3.1.3 Self‑test Cases

Using

lodash

we list several test cases and their outcomes:

^4.11.2

→

error

~4.11.2

→

error

^4.8.1

→

4.11.1

~4.8.1

→

4.8.2

^3.9.1

→

3.10.1

~3.9.1

→

3.9.3

^3.8.3

→

3.10.1

~3.8.3

→

error

^0.3.0

→

0.3.2

~0.3.0

→

0.3.2

3.1.4 npm install --save No Longer Uses ~

Since npm

v1.4.3

, the default

npm install --save

(and its variants) use the caret

^

specifier instead of the tilde.

Default npm install --save and its counterparts now use the ^ version specifier, instead of ~ . (0a3151c,@mikolalysenko)

3.2 Greater‑than or Less‑than Specifiers

Although less common, npm supports

>

and

<

operators.

>4.11.1

: latest version greater than 4.11.1.

<4.11.1

: latest version less than 4.11.1.

Test results:

>3.8.1

→

4.11.1

<3.8.1

→

3.8.0

3.3 Exact Version

Using an equals sign

=

or omitting any operator specifies an exact version, e.g.,

"lodash":"=3.8.0"

or

"lodash":"3.8.0"

. The same can be achieved with

npm install [email protected]

.

Further Reading

Difference between tilde(~) and caret(^) in package.json

"npm install --save" No Longer Using Tildes