npm version cheatsheet

npm_version_cheatsheet.md

npm version cheatsheet

npm uses Semantic Versioning

npm uses Semantic Versioning. Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards compatible manner, and
3. PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format, e.g. 1.0.0-alpha.

Acceptable version ranges

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

npm version symbols

Symbol	Rule	Example
^	accept updates to minor and patch releases only.	^0.13.0: 0.13.1, 0.14.0
~	accept updates to patch releases only.	~0.13.0: 0.13.1 (not 0.14.0)
>	accept updates to any version greater than the one specified.	>0.13.0: 0.13.1, 0.14.1, 1.1.1
<	accept updates to any version less than the one specified.	<3.0.0: 2.0.0, 2.9.0
>=	accept any version greater than or equal to the one specified.	>=3.0.0: 3.0.0, 4.1.0
<=	accept any version less than or equal to the one specified.	<=3.0.0: 3.0.0, 2.9.0
=	accept only the exact specified version.	=3.0.0: 3.0.0, (not 3.0.1)
-	accept a range of versions.	1.0.0 - 1.10.10: 1.5.0 (not 1.11.0)
||	accept a combination of versions.	<2.1.0 || >2.6.0: 2.0.1, 3.1.0
x.x.x	accept only the specified version (no symbol).	=3.0.0: 3.0.0, (not 3.0.1)
latest	always get latest version available.	<package-name>@latest

References

• npm Docs: About semantic versioning
• npm Docs: npm-version
• The semantic versioner for npm
• Flavio Copes: Semantic Versioning using npm

Resources

• npm semver calculator

Thanks for this! I think this example is wrong:

<= | accept any version less than or equal to the one specified. | <=3.0.0: 3.0.0, 4.1.0

should be something like:

<= | accept any version less than or equal to the one specified. | <=3.0.0: 3.0.0, 2.9.0 (not 4.1.0)

The table is WRONG in some of the rules and examples. Please refer to official documentation for exact meaning of symbols.

@masoud-msk: can you be more specific? Which examples?

@jonlabelle less-than or equal to example is wrong, 4.1.0 is greater than 3.0.0
<=3.0.0: 3.0.0, 4.1.0

@jonlabelle Also check the caret range (^)

@mark-at-tusksoft: less-than or equal to example is wrong, 4.1.0 is greater than 3.0.0 <=3.0.0: 3.0.0, 4.1.0

Fixed.

thanks, this was helpful. might be nice to add && operator.