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

Related to this question you can review [Composer documentation on versions][2], 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.

[1]:

[To see links please register here]

[2]:

[To see links please register here]

You should probably review [this stackoverflow post about differences between composer install and composer update][1].

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`.

[![semver table][1]][1]

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

[To see links please register here]

).

**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"](

[To see links please register here]

)

Here's a visual explanation of the concepts:

> ![semver diagram](

[To see links please register here]

)

Source: ["Semantic Versioning Cheatsheet"](

[To see links please register here]

).


[1]:

## Semver

<major>.<minor>.<patch>-beta.<beta> == 1.2.3-beta.2

- Use [npm semver calculator][1] 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](

[To see links please register here]

) instead, which doesn't require you to pick a package and also offers explanations.

## Allow or disallow changes

- Pin version: `1.2.3`.
- Use `^` (like head). Allows updates at the second non-zero level from the left: `^0.2.3` means `0.2.3 <= v < 0.3`.
- Use `~` (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`.
- Ommit right-most level: `0.2` means `0.2 <= v < 1`. Differs from `~` because:
- Starting omitted level version is always `0`
- You can set starting major version without specifying sublevels.

## All (hopefully) possibilities

**Set 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.

-

[To see links please register here]

-

[To see links please register here]

[1]:

[To see links please register here]

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](

[To see links please register here]

) 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)

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)`

Not an answer, per se, but an observation that seems to have been overlooked.

The description for caret ranges:

see:

[To see links please register here]

> 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.

**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:

- Patch releases: 1.0 or 1.0.x or ~1.0.4
- Minor releases: 1 or 1.x or ^1.0.4
- Major releases: * or x

For more information on semantic versioning syntax, see the [npm semver calculator][1].

[![npm semantic versions in published packages§][2]][2]

More from npm documentation [About semantic versioning][3]


[1]:

[To see links please register here]

[2]:

[3]:

[To see links please register here]

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 <br/> See [npm semver - Tilde Ranges][2] |
| `^version` | Compatible with version, i.e., accept new **minor and patch** versions <br/> See [npm semver - Caret Ranges][3] |
| `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

* [npm docs > package.json > dependencies][4]
* [npm docs > semver > versions][5]
* [semver (7)][1]


[1]:

[To see links please register here]

[2]:

[To see links please register here]

[3]:

[To see links please register here]

[4]:

[To see links please register here]

[5]:

[To see links please register here]

**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

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
```