/glossary/semver/pre-release-versions
SemVer pre-release versions: 1.0.0-alpha, -beta.2, -rc.1 and how they sort
- tool
- SemVer
- versions
- SemVer 2.0.0, semver (npm) 7
- os
- any
A pre-release version in Semantic Versioning is a version with a hyphen and dot-separated identifiers after the patch number, such as 1.0.0-alpha, 1.0.0-beta.2 or 2.1.0-rc.1. It ranks lower than the same version without the suffix (1.0.0-rc.1 < 1.0.0) and signals that the version may be unstable. Build metadata after a + (1.0.0+20261021) is different: it is ignored when comparing versions.
Precedence rules
SemVer 2.0.0 compares the identifiers one by one, left to right:
| Rule | Example |
|---|---|
| A pre-release is lower than the normal version | 1.0.0-alpha < 1.0.0 |
| Numeric identifiers compare as numbers | 1.0.0-beta.2 < 1.0.0-beta.10 |
| Alphanumeric identifiers compare in ASCII order | 1.0.0-alpha < 1.0.0-beta < 1.0.0-rc |
| Numeric identifiers are lower than alphanumeric ones | 1.0.0-1 < 1.0.0-alpha |
| More identifiers win when all earlier ones are equal | 1.0.0-alpha < 1.0.0-alpha.1 |
| Build metadata is ignored for precedence | 1.0.0+a and 1.0.0+b have the same precedence |
Check the order
npx -y semver@7 1.0.0 1.0.0-rc.1 1.0.0-beta.10 1.0.0-beta.2 1.0.0-alpha.1 1.0.0-alpha 1.0.0-1 | tr '\n' ' '
echoOutput
1.0.0-1 1.0.0-alpha 1.0.0-alpha.1 1.0.0-beta.2 1.0.0-beta.10 1.0.0-rc.1 1.0.0
The output is the order from the SemVer specification's own example list, with 1.0.0-1 added at the start.
Pre-releases and ranges in npm
npm ranges skip pre-releases by default, so ^1.2.0 does not match 1.3.0-beta.1. A pre-release is matched only when the range itself names a pre-release of the same major.minor.patch:
npx -y semver@7 -r "^1.2.0" 1.2.5 1.3.0-beta.1 # prints only 1.2.5
npx -y semver@7 -r "^1.3.0-beta.0" 1.3.0-beta.1 1.3.0 1.4.0-beta.1
npx -y semver@7 -p -r "^1.2.0" 1.3.0-beta.1Output
1.2.5 1.3.0-beta.1 1.3.0 1.3.0-beta.1
-p (includePrerelease) makes the range accept any pre-release in it. Publishing a pre-release with npm publish --tag next keeps it off the latest tag, so plain npm install pkg does not pick it up.
Valid identifiers
Identifiers use only ASCII letters, digits and hyphens, must not be empty, and numeric ones must not have leading zeros (1.0.0-01 is invalid, 1.0.0-0a is valid because it is alphanumeric).