What's the difference between tilde(~) and caret(^) in package.json?

Question

After I upgraded to latest stable node and npm, I tried npm install moment --save. It saves the entry in the package.json

Answer 1

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

Answer 2

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.

Answer 3

~ fixes major and minor numbers. It is used when you're ready to accept bug-fixes in your dependency, but don't want any potentially incompatible changes.

^ fixes the major number only. It is used when you're closely watching your dependencies and are ready to quickly change your code if minor release will be incompatible.

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.

Answer 4

Related to this question you can review Composer documentation on versions, but here in short:

• Tilde Version Range (~) - ~1.2.3 is equivalent to >=1.2.3 <1.3.0
• Caret Version Range (^) - ~1.2.3 is equivalent to >=1.2.3 <2.0.0

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.

Answer 5

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 -

https://docs.npmjs.com/files/package.json

https://docs.npmjs.com/misc/semver#x-ranges-12x-1x-12-

• ~version "Approximately equivalent to version" See npm semver - Tilde Ranges & semver (7)
• ^version "Compatible with version" See npm semver - Caret Ranges & semver (7)
• 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
• http://sometarballurl (this may be the URL of a tarball which will be downloaded and installed locally
• * 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

Answer 6

^ 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