.\" Generated by scdoc 1.11.4
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "RPM-VERSION" "7" "2026-01-08" "RPM 6.0.1"
.PP
.SH NAME
\fBrpm-version\fR - RPM version system
.PP
.SH SYNOPSIS
[\fIEPOCH\fR\fB:\fR]\fIVERSION\fR[\fB-\fR\fIRELEASE\fR]
.PP
.SH DESCRIPTION
A label known as \fIEVR\fR is used to refer to software versions in RPM,
consisting of up to three \fIcomponents\fR:
.PP
.PD 0
.IP \(bu 4
\fIVERSION\fR reflects the actual packaged software version.\&
.IP \(bu 4
\fIRELEASE\fR reflects packaging revisions within that software version.\&
.IP \(bu 4
\fIEPOCH\fR is an artificial override to allow working around versioning
anomalies.\&
.PD
.PP
Only the \fIVERSION\fR component is mandatory in an \fIEVR\fR label.\&
All RPM packages have a \fIVERSION\fR and a \fIRELEASE\fR, however.\&
.PP
.SS Version
The \fIVERSION\fR string reflects the actual packaged software version.\&
.PP
The string consists of ASCII alphanumeric characters, optionally
\fIsegmented\fR with the \fIseparators\fR period (\fB.\&\fR), underscore (\fB_\fR) and
the plus sign (\fB+\fR), and \fIoperators\fR tilde (\fB\(ti\fR) and caret (\fB\(ha\fR).\&
.PP
The \fIoperators\fR are used to map pre- and post-release version strings
into a coherent upgrade.\&
.PP
Notably, the dash character (\fB-\fR) can NOT be used in \fIVERSION\fR or \fIRELEASE\fR
as it is the component separator.\&
.PP
.SS Release
The \fIRELEASE\fR reflects a revision within a single software version.\&
Ideally, \fIRELEASE\fR is a simple integer that is incremented whenever changes
are made to a package, and should be reset (to 1) whenever the software
version changes.\&
.PP
Technically, the format is exactly the same as for \fIVERSION\fR.\&
.PP
.SS Epoch
The \fIEPOCH\fR is a non-negative integer, separated from the version with
a colon (\fB:\fR).\& It'\&s the most significant part of an
\fIEVR\fR, skewing version comparison to make an older version to appear newer.\&
It'\&s sometimes necessary to work around version anomalies such as a software
project changing its versioning scheme, but also packaging errors.\&
.PP
An omitted \fIEPOCH \fR has an implicit value of zero.\&
.PP
The epoch should be only used as a last resort.\& It violates the principle
of least surprise, and changing it requires all related versioned
dependencies in other packages to be updated accordingly.\&
.PP
.SS Comparing
Two \fIEVR\fRs are compared left to right, one component at a time.\&
The components are compared left to right, a \fIsegment\fR at a time.\&
The comparison stops as soon as a segment or component level difference
is found, so if eg.\& the epochs differ, the rest of the \fIEVR\fR is not
considered at all.\&
.PP
Within components, consecutive alphabetic characters and consecutive numbers
form \fIimplicit segments\fR.\& \fIExplicit segments\fR are denoted by \fIseparators\fR
and \fIoperators\fR.\&
Numeric segments are compared numerically as integers with leading zeros
ignored, otherwise lexicographical comparison is used.\&
That is, \fBabc123\fR consists of two segments: \fBabc\fR and \fB123\fR and is equal
to \fBabc0123\fR, \fBabc.\&123\fR and \fBabc.\&000123\fR despite difference in appearance.\&
.PP
Numeric segments are considered newer than alphabetic segments regardless
of the actual content.\& When otherwise equal, the component with more
segments is considered newer, and similarly an \fIEVR\fR with more components
is considered newer.\& For example, \fB0.\&0\fR is newer than \fB0\fR and \fB1.\&xyz\fR is
older than \fB1.\&0\fR but newer than \fB1\fR.\&
.PP
The segment \fIseparator\fR characters are not compared, so they can be used
interchangeably, and multiple consecutive separators are treated as if
only one separator was used.\& Thus, \fB1.\&0\fR is equal to \fB1+0\fR and \fB1+.\&+0\fR.\&
.PP
The tilde operator causes a segment to sort older, and is used for
\fIpre-release versions\fR.\& For example \fB2.\&0\(tibeta1\fR is older than \fB2.\&0\fR
or \fB2.\&0\(tirc1\fR, and newer than \fB1.\&0\fR.\&
The caret operator is essentially the opposite of tilde.\& It causes
a segment to sort newer, and is used for \fIpost-release snapshots\fR
that exist between actual software releases.\&
For example, \fB2.\&0\(ha150825\fR is newer than \fB2.\&0\fR but older than \fB2.\&0.\&1\fR.\&
.PP
.SH EXAMPLES
\fB123\fR
.RS 4
A simple one-segment version \fB123\fR.\& Newer than \fB99\fR, older
than \fB321\fR.\&
.PP
.RE
\fB1.\&0.\&1\fR
.RS 4
A segmented version string \fB1.\&0.\&1\fR, such as commonly used in software
projects to indicate major.\&minor.\&micro semantics.\& Newer than
\fB1.\&0\fR, older than \fB1.\&0.\&2\fR.\&
.PP
.RE
\fB2.\&60.\&1-1\fR
.RS 4
First release of version \fB2.\&60.\&1\fR.\& Newer than \fB2.\&0\fR or \fB2.\&60\fR,
but older than \fB3.\&0\fR.\&
.PP
.RE
\fB1.\&0-5\fR
.RS 4
Fifth release of version \fB1.\&0\fR, newer than \fB1.\&0\fR or \fB1.\&0-1\fR,
older than \fB1.\&0.\&1\fR.\&
.PP
.RE
\fB5:3.\&0-1\fR
.RS 4
First release of version \fB3.\&0\fR, with epoch of \fB5\fR.\& Newer
than for \fB6.\&0-1\fR, or \fB4:6.\&0-1\fR, older than \fB5:3.\&1-1\fR.\&
.PP
.RE
\fB1.\&0\(tibeta2\fR
.RS 4
Pre-release \fBbeta2\fR of version \fB1.\&0\fR.\& Newer than \fB0.\&99\fR and \fB1.\&0\(tibeta1\fR,
older than \fB1.\&0\fR.\&
.PP
.RE
\fB2.\&0\(ha20250611\fR
.RS 4
Post-release snapshot \fB20250611\fR of version \fB2.\&0\fR.\& Newer than \fB2.\&0\fR,
older than \fB2.\&0.\&1\fR.\&
.PP
.RE
.SH BUGS
Various non-obvious behaviors and dark corners exist within the version
comparison algorithm, but are difficult to address due to high risk of
breaking existing packages:
.PP
.PD 0
.IP \(bu 4
Non-ASCII characters are ignored and thus equal: \fB1.\&1.\&α\fR equals
\fB1.\&1.\&β\fR and even \fB1.\&1.\&ββ\fR.\& \fBrpmbuild\fR(1) rejects such EVRs but it'\&s
possible to encounter "illegal" values via API usage, very old packages
and packages created with 3rd party tools.\&
.IP \(bu 4
Implicit segments can be deceptive: \fB1.\&f\fR is newer than \fB1c.\&f\fR.\& The
result becomes more obvious by making the segments explicit:
\fB1.\&f\fR is newer than \fB1.\&c.\&f\fR because the segments are compared one
by one, and \fBc\fR sorts lower than \fBf\fR lexicographically.\&
.PD
.PP
\fBrpm\fR(8) \fBrpmbuild\fR(1) \fBrpmsort\fR(1)
.PP
\fBhttp://www.\&rpm.\&org/\fR