npm version cheatsheet

npm_version_cheatsheet.md

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.

Version range syntax

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 (for versions ≥1.0.0)
• Patch-only releases: ^0.13.0 (for versions starting with 0.x.y)
• Exact version only: ^0.0.x (for versions starting with 0.0.x)
• Major releases: * or x

Version range operators and specifiers

Symbol	Rule	Example
^	allows changes that do not modify the leftmost non-zero digit.	^1.13.0: 1.13.1, 1.14.0 (not 2.0.0) ^0.13.0: 0.13.1 (not 0.14.0) ^0.0.3: only 0.0.3
~	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 (OR logic).	<2.1.0 || >2.6.0: 2.0.1, 3.1.0
&&	accept versions that satisfy both conditions (AND logic).	>=1.0.0 && <2.0.0: 1.5.0 (not 2.0.0)
(space)	implicit AND operation (same as &&).	>=1.0.0 <2.0.0: 1.5.0 (not 2.0.0)
*	accept any version (wildcard).	*: any version available
x	accept any version for that position.	1.x: 1.0.0, 1.5.0 (not 2.0.0)
X	same as x (case insensitive wildcard).	1.X: 1.0.0, 1.5.0 (not 2.0.0)
(none)	accept only the exact specified version.	3.0.0: 3.0.0 (not 3.0.1)
latest	always get latest version available.	npm install <package>@latest
@tag	install a specific dist-tag.	npm install react@beta
file:	install from local file/directory.	file:../my-package
workspace:	reference workspace package (monorepos).	workspace:*, workspace:^1.0.0

Build metadata and pre-release precedence

• Build metadata (e.g., 1.0.0+20230101) is ignored when determining version precedence
• Pre-release versions are always less than their normal version (e.g., 1.0.0-alpha < 1.0.0)
• Multiple pre-release identifiers are compared lexically: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta

npm CLI version bump commands

Update your package version using npm commands:

Command	Version change	Example: 1.0.0 →
npm version patch	Bug fixes	1.0.1
npm version minor	New features	1.1.0
npm version major	Breaking changes	2.0.0
npm version prepatch	Pre-release patch	1.0.1-0
npm version preminor	Pre-release minor	1.1.0-0
npm version premajor	Pre-release major	2.0.0-0
npm version prerelease	Increment pre-release	1.0.1-0 → 1.0.1-1
npm version 1.2.3	Set specific version	1.2.3
npm version from-git	Use git tag version	(reads from git tags)

Note

--no-git-tag-version to skip git tag creation.

Pre-release version format

Pre-release versions are denoted by appending a hyphen and identifiers:

• 1.0.0-alpha: Alpha release
• 1.0.0-alpha.1: First alpha release
• 1.0.0-beta: Beta release
• 1.0.0-rc.1: Release candidate

Important

^1.0.0 will not match pre-release versions like 1.0.1-alpha.

package.json examples

{
  "dependencies": {
    "express": "^4.18.0", // Allow minor updates: 4.18.x, 4.19.x
    "lodash": "~4.17.21", // Allow patch updates: 4.17.x only
    "react": ">=18.0.0", // Any version 18.0.0 or higher
    "typescript": "4.x", // Any version in the 4.x series
    "eslint": "*", // Always get the latest version
    "axios": ">=1.0.0 && <2.0.0", // Must be 1.x series only
    "my-utils": "workspace:^1.0.0", // Workspace dependency
    "local-pkg": "file:../local-package" // Local file dependency
  },
  "devDependencies": {
    "jest": "29.0.0 - 29.5.0", // Specific range
    "prettier": "2.8.8", // Exact version
    "@types/node": ">=16.0.0 <21.0.0" // Space-separated AND
  }
}

Common gotchas and edge cases

• ^0.x.y behaves differently than ^1.x.y:
  • ^1.13.0 allows 1.13.1 and 1.14.0 (minor and patch updates)
  • ^0.13.0 allows only 0.13.1, 0.13.2, etc. (only patch updates)
  • ^0.0.3 allows only the exact version (0.0.3)
• Pre-release versions require explicit specification
• npm update respects semver ranges in package.json
• Empty version strings or invalid formats will cause errors
• latest tag may not always be the highest version number (it's whatever the maintainer tagged as latest)
• Ranges with spaces need quotes in command line: npm install "package@>=1.0.0 <2.0.0"

Useful npm commands

# Check outdated packages
npm outdated

# Update packages within semver ranges
npm update

# Install specific version
npm install [email protected]

# Install latest version
npm install package@latest

# Install pre-release version
npm install package@beta

# Show package versions
npm list

# Show available versions of a package
npm view package versions --json

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

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.

@jonlabelle as other said, chart wrong in many places. E.g.

^ accept updates to minor and patch releases only. | ^0.13.0: 0.13.1, 0.14.0

nope. ^ works that way (updates to minor and patch releases) only if the first value is non-zero; ^0.13.0 would only match 0.13.x and NOT 0.14.0 - from official doc:

Allows changes that do not modify the left-most non-zero element 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.

Thanks @FyiurAmron... should be fixed now.