| 1 |
.\" Generated by scdoc 1.11.4 |
| 2 |
.\" Complete documentation for this program is not available as a GNU info page |
| 3 |
.ie \n(.g .ds Aq \(aq |
| 4 |
.el .ds Aq ' |
| 5 |
.nh |
| 6 |
.ad l |
| 7 |
.\" Begin generated content: |
| 8 |
.TH "RPM-VERSION" "7" "2026-04-10" "RPM 6.0.1" |
| 9 |
.PP |
| 10 |
.SH NAME |
| 11 |
\fBrpm-version\fR - RPM version system |
| 12 |
.PP |
| 13 |
.SH SYNOPSIS |
| 14 |
[\fIEPOCH\fR\fB:\fR]\fIVERSION\fR[\fB-\fR\fIRELEASE\fR] |
| 15 |
.PP |
| 16 |
.SH DESCRIPTION |
| 17 |
A label known as \fIEVR\fR is used to refer to software versions in RPM, |
| 18 |
consisting of up to three \fIcomponents\fR: |
| 19 |
.PP |
| 20 |
.PD 0 |
| 21 |
.IP \(bu 4 |
| 22 |
\fIVERSION\fR reflects the actual packaged software version.\& |
| 23 |
.IP \(bu 4 |
| 24 |
\fIRELEASE\fR reflects packaging revisions within that software version.\& |
| 25 |
.IP \(bu 4 |
| 26 |
\fIEPOCH\fR is an artificial override to allow working around versioning |
| 27 |
anomalies.\& |
| 28 |
.PD |
| 29 |
.PP |
| 30 |
Only the \fIVERSION\fR component is mandatory in an \fIEVR\fR label.\& |
| 31 |
All RPM packages have a \fIVERSION\fR and a \fIRELEASE\fR, however.\& |
| 32 |
.PP |
| 33 |
.SS Version |
| 34 |
The \fIVERSION\fR string reflects the actual packaged software version.\& |
| 35 |
.PP |
| 36 |
The string consists of ASCII alphanumeric characters, optionally |
| 37 |
\fIsegmented\fR with the \fIseparators\fR period (\fB.\&\fR), underscore (\fB_\fR) and |
| 38 |
the plus sign (\fB+\fR), and \fIoperators\fR tilde (\fB\(ti\fR) and caret (\fB\(ha\fR).\& |
| 39 |
.PP |
| 40 |
The \fIoperators\fR are used to map pre- and post-release version strings |
| 41 |
into a coherent upgrade.\& |
| 42 |
.PP |
| 43 |
Notably, the dash character (\fB-\fR) can NOT be used in \fIVERSION\fR or \fIRELEASE\fR |
| 44 |
as it is the component separator.\& |
| 45 |
.PP |
| 46 |
.SS Release |
| 47 |
The \fIRELEASE\fR reflects a revision within a single software version.\& |
| 48 |
Ideally, \fIRELEASE\fR is a simple integer that is incremented whenever changes |
| 49 |
are made to a package, and should be reset (to 1) whenever the software |
| 50 |
version changes.\& |
| 51 |
.PP |
| 52 |
Technically, the format is exactly the same as for \fIVERSION\fR.\& |
| 53 |
.PP |
| 54 |
.SS Epoch |
| 55 |
The \fIEPOCH\fR is a non-negative integer, separated from the version with |
| 56 |
a colon (\fB:\fR).\& It'\&s the most significant part of an |
| 57 |
\fIEVR\fR, skewing version comparison to make an older version to appear newer.\& |
| 58 |
It'\&s sometimes necessary to work around version anomalies such as a software |
| 59 |
project changing its versioning scheme, but also packaging errors.\& |
| 60 |
.PP |
| 61 |
An omitted \fIEPOCH \fR has an implicit value of zero.\& |
| 62 |
.PP |
| 63 |
The epoch should be only used as a last resort.\& It violates the principle |
| 64 |
of least surprise, and changing it requires all related versioned |
| 65 |
dependencies in other packages to be updated accordingly.\& |
| 66 |
.PP |
| 67 |
.SS Comparing |
| 68 |
Two \fIEVR\fRs are compared left to right, one component at a time.\& |
| 69 |
The components are compared left to right, a \fIsegment\fR at a time.\& |
| 70 |
The comparison stops as soon as a segment or component level difference |
| 71 |
is found, so if eg.\& the epochs differ, the rest of the \fIEVR\fR is not |
| 72 |
considered at all.\& |
| 73 |
.PP |
| 74 |
Within components, consecutive alphabetic characters and consecutive numbers |
| 75 |
form \fIimplicit segments\fR.\& \fIExplicit segments\fR are denoted by \fIseparators\fR |
| 76 |
and \fIoperators\fR.\& |
| 77 |
Numeric segments are compared numerically as integers with leading zeros |
| 78 |
ignored, otherwise lexicographical comparison is used.\& |
| 79 |
That is, \fBabc123\fR consists of two segments: \fBabc\fR and \fB123\fR and is equal |
| 80 |
to \fBabc0123\fR, \fBabc.\&123\fR and \fBabc.\&000123\fR despite difference in appearance.\& |
| 81 |
.PP |
| 82 |
Numeric segments are considered newer than alphabetic segments regardless |
| 83 |
of the actual content.\& When otherwise equal, the component with more |
| 84 |
segments is considered newer, and similarly an \fIEVR\fR with more components |
| 85 |
is considered newer.\& For example, \fB0.\&0\fR is newer than \fB0\fR and \fB1.\&xyz\fR is |
| 86 |
older than \fB1.\&0\fR but newer than \fB1\fR.\& |
| 87 |
.PP |
| 88 |
The segment \fIseparator\fR characters are not compared, so they can be used |
| 89 |
interchangeably, and multiple consecutive separators are treated as if |
| 90 |
only one separator was used.\& Thus, \fB1.\&0\fR is equal to \fB1+0\fR and \fB1+.\&+0\fR.\& |
| 91 |
.PP |
| 92 |
The tilde operator causes a segment to sort older, and is used for |
| 93 |
\fIpre-release versions\fR.\& For example \fB2.\&0\(tibeta1\fR is older than \fB2.\&0\fR |
| 94 |
or \fB2.\&0\(tirc1\fR, and newer than \fB1.\&0\fR.\& |
| 95 |
The caret operator is essentially the opposite of tilde.\& It causes |
| 96 |
a segment to sort newer, and is used for \fIpost-release snapshots\fR |
| 97 |
that exist between actual software releases.\& |
| 98 |
For example, \fB2.\&0\(ha150825\fR is newer than \fB2.\&0\fR but older than \fB2.\&0.\&1\fR.\& |
| 99 |
.PP |
| 100 |
.SH EXAMPLES |
| 101 |
\fB123\fR |
| 102 |
.RS 4 |
| 103 |
A simple one-segment version \fB123\fR.\& Newer than \fB99\fR, older |
| 104 |
than \fB321\fR.\& |
| 105 |
.PP |
| 106 |
.RE |
| 107 |
\fB1.\&0.\&1\fR |
| 108 |
.RS 4 |
| 109 |
A segmented version string \fB1.\&0.\&1\fR, such as commonly used in software |
| 110 |
projects to indicate major.\&minor.\µ semantics.\& Newer than |
| 111 |
\fB1.\&0\fR, older than \fB1.\&0.\&2\fR.\& |
| 112 |
.PP |
| 113 |
.RE |
| 114 |
\fB2.\&60.\&1-1\fR |
| 115 |
.RS 4 |
| 116 |
First release of version \fB2.\&60.\&1\fR.\& Newer than \fB2.\&0\fR or \fB2.\&60\fR, |
| 117 |
but older than \fB3.\&0\fR.\& |
| 118 |
.PP |
| 119 |
.RE |
| 120 |
\fB1.\&0-5\fR |
| 121 |
.RS 4 |
| 122 |
Fifth release of version \fB1.\&0\fR, newer than \fB1.\&0\fR or \fB1.\&0-1\fR, |
| 123 |
older than \fB1.\&0.\&1\fR.\& |
| 124 |
.PP |
| 125 |
.RE |
| 126 |
\fB5:3.\&0-1\fR |
| 127 |
.RS 4 |
| 128 |
First release of version \fB3.\&0\fR, with epoch of \fB5\fR.\& Newer |
| 129 |
than for \fB6.\&0-1\fR, or \fB4:6.\&0-1\fR, older than \fB5:3.\&1-1\fR.\& |
| 130 |
.PP |
| 131 |
.RE |
| 132 |
\fB1.\&0\(tibeta2\fR |
| 133 |
.RS 4 |
| 134 |
Pre-release \fBbeta2\fR of version \fB1.\&0\fR.\& Newer than \fB0.\&99\fR and \fB1.\&0\(tibeta1\fR, |
| 135 |
older than \fB1.\&0\fR.\& |
| 136 |
.PP |
| 137 |
.RE |
| 138 |
\fB2.\&0\(ha20250611\fR |
| 139 |
.RS 4 |
| 140 |
Post-release snapshot \fB20250611\fR of version \fB2.\&0\fR.\& Newer than \fB2.\&0\fR, |
| 141 |
older than \fB2.\&0.\&1\fR.\& |
| 142 |
.PP |
| 143 |
.RE |
| 144 |
.SH BUGS |
| 145 |
Various non-obvious behaviors and dark corners exist within the version |
| 146 |
comparison algorithm, but are difficult to address due to high risk of |
| 147 |
breaking existing packages: |
| 148 |
.PP |
| 149 |
.PD 0 |
| 150 |
.IP \(bu 4 |
| 151 |
Non-ASCII characters are ignored and thus equal: \fB1.\&1.\&α\fR equals |
| 152 |
\fB1.\&1.\&β\fR and even \fB1.\&1.\&ββ\fR.\& \fBrpmbuild\fR(1) rejects such EVRs but it'\&s |
| 153 |
possible to encounter "illegal" values via API usage, very old packages |
| 154 |
and packages created with 3rd party tools.\& |
| 155 |
.IP \(bu 4 |
| 156 |
Implicit segments can be deceptive: \fB1.\&f\fR is newer than \fB1c.\&f\fR.\& The |
| 157 |
result becomes more obvious by making the segments explicit: |
| 158 |
\fB1.\&f\fR is newer than \fB1.\&c.\&f\fR because the segments are compared one |
| 159 |
by one, and \fBc\fR sorts lower than \fBf\fR lexicographically.\& |
| 160 |
.PD |
| 161 |
.PP |
| 162 |
\fBrpm\fR(8) \fBrpmbuild\fR(1) \fBrpmsort\fR(1) |
| 163 |
.PP |
| 164 |
\fBhttp://www.\&rpm.\&org/\fR |