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.
npm?~ and caret ^?
See the NPM docs and semver docs:
~version “Approximately equivalent to version”, will automatically update you to all future patch versions that are backwards-compatible, without incrementing the minor version. ~1.2.3 will use releases from 1.2.3 to < 1.3.0.
^version “Compatible with version”, will automatically update you to all future minor/patch versions that are backwards-compatible, without incrementing the major version. ^1.2.3 will use releases from 1.2.3 to < 2.0.0.
See Comments below for exceptions, in particular for pre-one versions, such as ^0.2.3
^ or a ~. Set this if you want to have tight control over your versions: npm config set save-prefix=''
Commented
Jul 8, 2015 at 6:11
0.2.x, 2 isn't a major version. That's why docs.npmjs.com used the specific words: the left-most non-zero digit. Also what about this case: ^0.0.4 means 0.0.4
A in 3 versions: 0.0.1, 0.0.2 and 0.0.3. There is a bug in 0.0.1 so you want to have at least 0.0.2 in your package B. If you write 0.0.x you'll get 0.0.3, which is OK. But if some other package C requires both B and A and additionally has constrain "A": "<0.0.2" you'll get 0.0.1 without showing any conflict issue, which is not what you want. Using tilde ~0.0.2 should help you avoid this issue.
Commented
Oct 22, 2015 at 14:22
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 |
Must be equal or greater than version |
<version |
Must be lesser than version |
<=version |
Must be equal or lesser than 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
1.2.0 || >=1.2.2 <1.3.0: Exactly 1.2.0, or everything from 1.2.2 to 1.3.0 (inclusive), but not 1.2.1, or 1.3.1 and above, and also not 1.1.x and below.
"Approximately equivalent to version" and "Compatible with version" are such frustratingly non-specific ways to describe ~ and ^ behavior. Thank you @jgillich for providing an actual answer!
Commented
Jul 17, 2019 at 15:21
0, yes they are equivalent. But if you had, for example, ~1.2.3, that's equivalent to >=1.2.3 <1.3.0, whereas 1.2.x would be equivalent to >=1.2.0 <1.3.0 --- essentially the ~ means any patch version greater than or equal to the one specified, whereas the x in that position means any number. Full syntax is defined here: github.com/npm/node-semver#advanced-range-syntax
Commented
Jul 6, 2023 at 2:02
The package manager npm allows installing a newer package version than the one specified.
Using tilde (~) gives you bug-fix releases, while caret (^) in addition gives you backward-compatible new functionality.
The problem is that old versions usually don't receive bug fixes, so npm uses caret (^) as the default for --save.
Source: "SemVer explained - why there's a caret (^) in my package.json?".
Note that the rules apply to versions above 1.0.0. 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".
<major>.<minor>.<patch>-beta.<beta> == 1.2.3-beta.2
1.2.3.^ (like head). Allows updates at the second non-zero level from the left: ^0.2.3 means 0.2.3 <= v < 0.3.~ (like tail). Generally freeze right-most level or set zero if omitted:~1 means 1.0.0 <= v < 2.0.0~1.2 means 1.2.0 <= v < 1.3.0.~1.2.4 means 1.2.4 <= v < 1.3.0.0.2 means 0.2 <= v < 1. Differs from ~ because:
0Set starting major-level and allow updates upward
* or "(empty string) any version
1 v >= 1
Freeze major-level
~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
Freeze minor-level
^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
Freeze patch-level
~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)
Disallow updates
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 npm sets ^ 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.
So, ^ 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)
~ : Reasonably close to
~1.1.5: 1.1.0 <= accepted < 1.2.0
^: Compatible with
^1.1.5: 1.1.5 <= accepted < 2.0.0
^0.1.3: 0.1.3 <= accepted < 0.2.0
^0.0.4: 0.0.4 <= accepted < 0.1.0
^0.1.3 only accepts versions 0.1.x and will not accept 0.2.0, even though that's a minor increment. This behavior is equivalent to ~0.1.3. The reasoning behind this behavior is due to the fact that zeroth-release packages are still considered unstable; in the words of semver.org, #4, "anything may change at any time" (including backwards-incompatible changes).
^ is 1.[any].[any] (latest minor version)
~ is 1.2.[any] (latest patch)
A great read is this blog post on how semver applies to npm
and what they're doing to make it match the semver standard
http://blog.npmjs.org/post/98131109725/npm-2-0-0
~ Tilde:
~ freezes major and minor numbers.^ Caret:
^ freezes the major number only.Hat matching may be considered "broken" because it wont update ^0.1.2 to 0.2.0. When the software is emerging use 0.x.y versions and hat matching will only match the last varying digit (y). This is done on purpose. The reason is that while the software is evolving the API changes rapidly: one day you have these methods and the other day you have those methods and the old ones are gone. If you don't want to break the code for people who already are using your library you go and increment the major version: e.g. 1.0.0 -> 2.0.0 -> 3.0.0. So, by the time your software is finally 100% done and full-featured it will be like version 11.0.0 and that doesn't look very meaningful, and actually looks confusing. If you were, on the other hand, using 0.1.x -> 0.2.x -> 0.3.x versions then by the time the software is finally 100% done and full-featured it is released as version 1.0.0 and it means "This release is a long-term service one, you can proceed and use this version of the library in your production code, and the author won't change everything tomorrow, or next month, and he won't abandon the package".
The rule is: use 0.x.y versioning when your software hasn't yet matured and release it with incrementing the middle digit when your public API changes (therefore people having ^0.1.0 won't get 0.2.0 update and it won't break their code). Then, when the software matures, release it under 1.0.0 and increment the leftmost digit each time your public API changes (therefore people having ^1.0.0 won't get 2.0.0 update and it won't break their code).
Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
caret ^ include everything greater than a particular version in the same major range.
tilde ~ include everything greater than a particular version in the same minor range.
For example, to specify acceptable version ranges up to 1.0.4, use the following syntax:
For more information on semantic versioning syntax, see the npm semver calculator.
More from npm documentation About semantic versioning
Tilde (~)
major version is fixed, the minor version is fixed, matches any build number
"express": "~4.13.3"
~4.13.3 means it will check for 4.13.x where x is anything
Caret (^)
major version is fixed, matches any minor version, matches any build number
"supertest": "^3.0.0"
^3.0.0 means it will check for 3.x.x where x is anything
One liner explanation
The standard versioning system is major.minor.build (e.g. 2.4.1)
npm checks and fixes the version of a particular package based on these characters
~ : major version is fixed, minor version is fixed, matches any build number
e.g. : ~2.4.1 means it will check for 2.4.x where x is anything
^ : major version is fixed, matches any minor version, matches any build number
e.g. : ^2.4.1 means it will check for 2.x.x where x is anything
Tilde ~ matches minor version, if you have installed a package that has 1.4.2 and after your installation, versions 1.4.3 and 1.4.4 are also available if in your package.json it is used as ~1.4.2 then npm install in your project after upgrade will install 1.4.4 in your project. But there is 1.5.0 available for that package then it will not be installed by ~. It is called minor version.
Caret ^ matches major version, if 1.4.2 package is installed in your project and after your installation 1.5.0 is released then ^ will install major version. It will not allow to install 2.1.0 if you have ^1.4.2.
Fixed version if you don't want to change version of package on each installation then used fixed version with out any special character e.g "1.4.2"
Latest Version * If you want to install latest version then only use * in front of package name.
You probably have seen the tilde (~) and caret (^) in the package.json. What is the difference between them?
When you do npm install moment --save, It saves the entry in the package.json with the caret (^) prefix.
In the simplest terms, the tilde (~) matches the most recent minor version (the middle number). ~1.2.3 will match all 1.2.x versions but will miss 1.3.0.
The caret (^), on the other hand, is more relaxed. It will update you to the most recent major version (the first number). ^1.2.3 will match any 1.x.x release including 1.3.0, but will hold off on 2.0.0.
Reference: https://medium.com/@Hardy2151/caret-and-tilde-in-package-json-57f1cbbe347b
This is an oversimplification, but a semantic version consists of 3 parts: the major version, minor version, and patch version. For example, 1.2.3 has a major version of 1, a minor version of 2, and a patch version of 3.
For the examples below, assume that the current package is app and it depends
on dep1. The published versions of dep1 are:
{
"dist-tags": { "latest": "1.2.2" },
"versions": [
"1.2.2",
"1.2.1",
"1.0.1",
"1.0.0",
"0.4.1",
"0.4.0",
"0.2.3",
"0.2.0",
"0.0.3",
"0.0.2",
"0.0.1"
]
}
I'll start with tilde because it's the most consistent. It will give you the latest patch version without changing the major or minor version.
| SemVer Range | Your node_module Version After npm update --save |
|---|---|
| ~1.2.1 | 1.2.2 |
| ~1.0.1 | 1.0.1 |
| ~1.0.0 | 1.0.1 |
| ~1.0.0 | 1.0.1 |
| ~0.4.1 | 0.4.1 |
| ~0.4.0 | 0.4.1 |
| ~0.2.3 | 0.2.3 |
| ~0.2.0 | 0.2.3 |
| ~0.0.3 | 0.0.3 |
| ~0.0.2 | 0.0.3 |
| ~0.0.1 | 0.0.3 |
Most think caret dependencies work like this: It will give you the latest minor version and patch version without changing the major version.
| SemVer Range | Your node_module Version After npm update --save |
|---|---|
| ^1.2.1 | 1.2.2 |
| ^1.0.1 | 1.2.2 |
| ^1.0.0 | 1.2.2 |
| ^1.0.0 | 1.2.2 |
But that's not the whole picture, this is only true when the major version is > 0. The next section explains how caret dependencies work regardless of the major version.
Here's a more comprehensive explanation: Imagine the major version, minor version, and patch version are elements of an array (e.g., [major, minor, patch]). The caret dependency iterates the array until it finds the first non-zero, it "freezes" that non-zero in place, then it updates the next element(s) to the latest. In other words, assuming x, y, and z represent numbers greater than 0:
^x.y.z will update y and z to the latest.^0.y.z will update z to the latest.^0.0.z won't update anything, because there is no element after z.Let's see this in action:
| SemVer Range | Your node_module Version After npm update --save |
|---|---|
| ^1.2.1 | 1.2.2 |
| ^1.0.1 | 1.2.2 |
| ^1.0.0 | 1.2.2 |
| ^1.0.0 | 1.2.2 |
| ^0.4.1 | 0.4.1 |
| ^0.4.0 | 0.4.1 |
| ^0.2.3 | 0.2.3 |
| ^0.2.0 | 0.2.3 |
| ^0.0.3 | 0.0.3 |
| ^0.0.2 | 0.0.2 |
| ^0.0.1 | 0.0.1 |
*: This language was taken from https://docs.npmjs.com/cli/v10/commands/npm-update#example and modified.
1.2.3. Lib adds a non-breaking, new feature and becomes version 1.3.0. Then somebody reports a security vulnerability that affects 1.2.3 and 1.3.0. They fix this bug and become version 1.3.1. If you only get new patch versions (i.e., ~1.2.3), you will continue to use Lib with the security vulnerability (1.2.3). But if you get the new minors and patches (i.e., ^1.2.3), you will get the latest secure version (1.3.1). Let me know if that's confusing because this is pretty complex to describe in SO comments.
Commented
Jan 20 at 1:33
semver is separate in to 3 major sections which is broken by dots.
major.minor.patch
1.0.0
These different major, minor and patch are using to identify different releases. tide (~) and caret (^) are using to identify which minor and patch version to be used in package versioning.
~1.0.1
Install 1.0.1 or **latest patch versions** such as 1.0.2 ,1.0.5
^1.0.1
Install 1.0.1 or **latest patch and minor versions** such as 1.0.2 ,1.1.0 ,1.1.1
Related to this question you can review Composer documentation on versions, but here in short:
So, with Tilde you will get automatic updates of patches but minor and major versions will not be updated. However, if you use Caret you will get patches and minor versions, but you will not get major (breaking changes) versions.
Tilde Version is considered "safer" approach, but if you are using reliable dependencies (well-maintained libraries) you should not have any problems with Caret Version (because minor changes should not be breaking changes.
You should probably review this stackoverflow post about differences between composer install and composer update.
Not an answer, per se, but an observation that seems to have been overlooked.
The description for caret ranges:
see: https://github.com/npm/node-semver#caret-ranges-123-025-004
Allows changes that do not modify the left-most non-zero digit in the [major, minor, patch] tuple.
Means that ^10.2.3 matches 10.2.3 <= v < 20.0.0
I don't think that's what they meant. Pulling in versions 11.x.x through 19.x.x will break your code.
I think they meant left most non-zero number field. There is nothing in SemVer that requires number-fields to be single-digit.
Allows changes that do not modify the left-most non-zero element.
For example for : ~1.8.0 you will match all of them 1.8.x versions, but you will lose 1.9.0 (This has been the default behavior).
For example for : ^1.8.0 you will be updated to the latest major version (the first issue). Any 1.x.x release including 1.9.0, but keeping the distance from version 2.0.0
Example 3.9.2:
Symbol Dependency Versions Changes
tilde (~) ~3.9.2 3.9.* -bug fix
caret (^) ^3.9.2 3.*.* -backwards compatible new functionality
-old functionality deprecated, but operational
-large internal refactor
-bug fix
The version number is in syntax which designates each section with different meaning. syntax is broken into three sections separated by a dot.
major.minor.patch 1.0.2
Major, minor and patch represent the different releases of a package.
npm uses the tilde (~) and caret (^) to designate which patch and minor versions to use respectively.
So if you see ~1.0.2 it means to install version 1.0.2 or the latest patch version such as 1.0.4. If you see ^1.0.2 it means to install version 1.0.2 or the latest minor or patch version such as 1.1.0.
Tilde ~ specifies to minor version releases
Caret ^ specifies to major version releases
For example, if package version is 4.5.2, on update:
~4.5.2 will install latest 4.5.x version (MINOR VERSION)
^4.5.2 will install latest 4.x.x version (MAJOR VERSION)
According to semver docs:
Allows patch-level changes if a minor version is specified on the comparator. Allows minor-level changes if not.
For eg
Allows changes that do not modify the left-most non-zero digit in the [major, minor, patch] tuple. In other words, this allows patch and minor updates for versions 1.0.0 and above, patch updates for versions 0.X >=0.1.0, and no updates for versions 0.0.X.
Note: Many authors treat a 0.x version as if the x were the major "breaking-change" indicator.
For eg
npm config set save-prefix=''. (Stick~in the quotes if that's what you prefer.) I personally do this and shrinkwrap for things in production.npm shrinkwrapand package-lock.json vs npm-shrinkwrap.json #toSaveYouAGoogle (or two) -- fncomp mentions above and tehfoo below. Also, mneumonic:~stays about even,^goes up a little higher.