What's the Difference Between Tilde(~) and Caret(^) in Package. Json?

Elena Rostova
Elena Rostova
• • 11 min read

After I Upgraded to the Latest Stable Node and Npm, I Tried Npm Install Moment --Save. It Saves the Entry in the Package. Json with the Caret ^ Prefix...

What's the Difference Between Tilde(~) and Caret(^) in Package. Json?

After I upgraded to the latest stable node and npm, I tried npm install moment --save. It saves the entry in the package.json with the caret ^ prefix. Previously, it was a tilde ~ prefix.

  1. Why are these changes made in npm?
  2. What is the difference between tilde ~ and caret ^?
  3. What are the advantages over others?
5

19 Answers

See the NPM docs and semver docs:

  • ~version “Approximately equivalent to version”, will update you to all future patch versions, without incrementing the minor version. ~1.2.3 will use releases from 1.2.3 to <1.3.0.

  • ^version “Compatible with version”, will update you to all future minor/patch versions, without incrementing the major version. ^2.3.4 will use releases from 2.3.4 to <3.0.0.

See Comments below for exceptions, in particular for pre-one versions, such as ^0.2.3

20

I would like to add the official npmjs documentation as well which describes all methods for version specificity including the ones referred to in the question

value desc
~version Approximately equivalent to version, i.e., only accept new patch versions
See npm semver - Tilde Ranges
^version Compatible with version, i.e., accept new minor and patch versions
See npm semver - Caret Ranges
version Must match version exactly
>version Must be greater than version
>=version etc
<version
<=version
1.2.x 1.2.0, 1.2.1, etc., but not 1.3.0
* Matches any version
latest Obtains latest release

The above list is not exhaustive. Other version specifiers include GitHub urls and GitHub user repo's, local paths and packages with specific npm tags

Official Docs

7

npm allows installing newer version of a package than the one specified. Using tilde (~) gives you bug fix releases and caret (^) gives you backwards-compatible new functionality as well.

The problem is old versions usually don't receive bug fixes that much, so npm uses caret (^) as the default for --save.

According to: "Semver explained - why there's a caret (^) in my package.json?".

Note that the rules apply to versions above 1.0.0 and not every project follows semantic versioning. For versions 0.x.x the caret allows only patch updates, i.e., it behaves the same as the tilde. See "Caret Ranges"

Here's a visual explanation of the concepts:

Source: "Semantic Versioning Cheatsheet".

9

Must Read

Semver

<major>.<minor>.<patch>-beta.<beta> == 1.2.3-beta.2
  • Use npm semver calculator for testing. Although the explanations for ^ (include everything greater than a particular version in the same major range) and ~ (include everything greater than a particular version in the same minor range) aren't a 100% correct, the calculator seems to work fine.
  • Alternatively, use SemVer Check instead, which doesn't require you to pick a package and also offers explanations.
Elena Rostova

Elena Rostova

Lead Health, Wellness & Medical Journalist
Instagram Linkedin Twitter

Elena Rostova holds a Master's degree in Public Health Journalism. She covers groundbreaking medical research, holistic wellness trends, mental health awareness, and nutritional science.