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.

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
• Major releases: * or x

Version range operators and specifiers

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 (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: ^0.13.0 allows 0.13.1 but not 0.14.0
• ^0.0.x only allows patch updates: ^0.0.3 allows only 0.0.3, 0.0.4, etc.
• 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

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.