After I upgraded to the latest stable
npm, I tried
npm install moment --save. It saves the entry in the
package.json with the caret
^ prefix. Previously, it was a tilde
In this post, we’ll be discussing the following queries:
- Why are these changes made in
- What is the difference between tilde
- What are the advantages over others?
~version“Approximately equivalent to version”, will update you to all future patch versions, without incrementing the minor version.
~1.2.3will 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.4will use releases from 2.3.4 to <3.0.0.
Tilde vs caret in package.json – Answer #2:
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
|“Approximately equivalent to version”|
See npm semver – Tilde Ranges
|“Compatible with version”|
See npm semver – Caret Ranges
|Must match version exactly|
|Must be greater than version|
|1.2.0, 1.2.1, etc., but not 1.3.0|
|Matches any version|
|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
npm allows installing a 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
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
Here’s a visual explanation of the concepts:
<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.
Allow or disallow changes
- Pin version:
^(like head). Allows updates at the second non-zero level from the left:
0.2.3 <= v < 0.3.
~(like tail). Generally freeze right-most level or set zero if omitted:
1.0.0 <= v < 2.0.0
1.2.0 <= v < 1.3.0.
1.2.4 <= v < 1.3.0.
- Ommit right-most level:
0.2 <= v < 1. Differs from
- Starting omitted level version is always
- You can set starting major version without specifying sublevels.
- Starting omitted level version is always
All (hopefully) possibilities
Set starting major-level and allow updates upward
* or "(empty string) any version 1 v >= 1
~0 (0) 0.0 <= v < 1 0.2 0.2 <= v < 1 // Can't do that with ^ or ~ ~1 (1, ^1) 1 <= v < 2 ^1.2 1.2 <= v < 2 ^1.2.3 1.2.3 <= v < 2 ^1.2.3-beta.4 1.2.3-beta.4 <= v < 2
^0.0 (0.0) 0 <= v < 0.1 ~0.2 0.2 <= v < 0.3 ~1.2 1.2 <= v < 1.3 ~0.2.3 (^0.2.3) 0.2.3 <= v < 0.3 ~1.2.3 1.2.3 <= v < 1.3
~1.2.3-beta.4 1.2.3-beta.4 <= v < 1.2.4 (only beta or pr allowed) ^0.0.3-beta 0.0.3-beta.0 <= v < 0.0.4 or 0.0.3-pr.0 <= v < 0.0.4 (only beta or pr allowed) ^0.0.3-beta.4 0.0.3-beta.4 <= v < 0.0.4 or 0.0.3-pr.4 <= v < 0.0.4 (only beta or pr allowed)
1.2.3 1.2.3 ^0.0.3 (0.0.3) 0.0.3
Notice: Missing major, minor, patch or specifying
beta without number, is the same as
any for the missing level.
Notice: When you install a package which has
0 as major level, the update will only install new beta/pr level version! That’s because
^ as default in
package.json and when installed version is like
0.1.3, it freezes all major/minor/patch levels.
As long as the first number (“major”) is at least 1:
~ locks major and minor numbers. It is used when you’re ready to accept only bug-fixes (increments in the third number), but don’t want any other changes, not even minor upgrades that add features.
^ locks the major number only. It is used when you are willing to receive bug fixes (increments in the third number) and minor upgrades that add features but should not break existing code (increments in the second number). However you do not want changes that break existing code (increments in the first number).
In addition to that,
^ is not supported by old npm versions, and should be used with caution.
^ is a good default, but it’s not perfect. I suggest to carefully pick and configure the semver operator that is most useful to you.
(Revised to avoid saying “fixes” and “bug-fixes” with conflicting use of “fixes”, which is confusing).
Hope you learned something from this post.
Follow Programming Articles for more!