In Semantic Versioning a pre-release version always has lower precedence than the normal version it precedes, so 1.0.0-rc.1 sorts before 1.0.0. Build metadata after a plus sign is ignored when comparing. Update logic that gets this wrong can push customers onto test builds or skip fixes.
Definitions
A pre-release is a hyphen followed by dot separated identifiers after the patch number, such as 1.0.0-alpha.1. The spec says it signals that the version is unstable. Build metadata is a plus sign and identifiers, such as 1.0.0+20130313144700. The spec says versions that differ only in build metadata have equal precedence.
How comparison works
For two pre-releases with the same core version, the spec compares identifiers from left to right. Numeric identifiers compare as numbers. Text identifiers compare in ASCII order. A numeric identifier ranks below a text one. If all earlier identifiers match, the longer list ranks higher.
| Version A | Version B | Higher |
|---|---|---|
| 1.0.0-rc.1 | 1.0.0 | 1.0.0 |
| 1.0.0-rc.2 | 1.0.0-rc.10 | 1.0.0-rc.10 |
| 1.0.0-alpha | 1.0.0-beta | 1.0.0-beta |
| 1.0.0-1 | 1.0.0-alpha | 1.0.0-alpha |
| 1.0.0+build5 | 1.0.0+build9 | Equal |
Notice rc.2 against rc.10. If you compare as plain text, rc.10 loses. The spec compares the numeric part as a number.
Why it matters for self-hosted products
Your update client or your customers' tooling has to pick the newest version it should install. Three mistakes show up often.
- A naive string sort that ranks 1.10.0 below 1.9.0.
- A client that treats any higher precedence as installable, so a stable channel customer receives a release candidate. Keep pre-releases on a separate channel and filter them by default.
- Using build metadata to tell two builds apart, then expecting the client to treat them as different. The spec says they are equal in precedence, so put anything that must differ into the pre-release part or a new patch number.
A short test list for your updater
Write unit tests for these cases before you ship a client:
- 1.0.0-rc.1 is older than 1.0.0.
- 1.9.0 is older than 1.10.0.
- Two builds that differ only after the plus sign are treated as the same release.
- A stable channel never offers a pre-release.
These are cheap tests, and they prevent a class of support tickets that read like a security incident when they are only a sort bug.
Where this connects to security
A fix shipped only as a pre-release does not reach stable customers. If you must ship an emergency fix first as a candidate, promote it to a normal patch version quickly and say so in the advisory. See also update channels and their security tradeoffs.
If you want a second look at what you ship, Safeguard can generate and scan an SBOM and run dependency scanning with reachability analysis, and you can try the free scan.
Quick check
Does 1.0.0+build5 install over 1.0.0+build4?
By the spec they have equal precedence, so a client following it sees no newer version. Use a new patch number when the content changes.
Is a pre-release safe for production?
The spec describes a pre-release as unstable. Keep it on an opt in channel.
Sources
Last reviewed: 19 October 2026.
