1SEMVER(7)                                                            SEMVER(7)
2
3
4

NAME

6       semver - The semantic versioner for npm
7

Install

9         npm install --save semver
10

Usage

12       As a node module:
13
14         const semver = require('semver')
15
16         semver.valid('1.2.3') // '1.2.3'
17         semver.valid('a.b.c') // null
18         semver.clean('  =v1.2.3   ') // '1.2.3'
19         semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
20         semver.gt('1.2.3', '9.8.7') // false
21         semver.lt('1.2.3', '9.8.7') // true
22         semver.minVersion('>=1.0.0') // '1.0.0'
23         semver.valid(semver.coerce('v2')) // '2.0.0'
24         semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
25
26       As a command-line utility:
27
28         $ semver -h
29
30         A JavaScript implementation of the https://semver.org/ specification
31         Copyright Isaac Z. Schlueter
32
33         Usage: semver [options] <version> [<version> [...]]
34         Prints valid versions sorted by SemVer precedence
35
36         Options:
37         -r --range <range>
38                 Print versions that match the specified range.
39
40         -i --increment [<level>]
41                 Increment a version by the specified level.  Level can
42                 be one of: major, minor, patch, premajor, preminor,
43                 prepatch, or prerelease.  Default level is 'patch'.
44                 Only one version may be specified.
45
46         --preid <identifier>
47                 Identifier to be used to prefix premajor, preminor,
48                 prepatch or prerelease version increments.
49
50         -l --loose
51                 Interpret versions and ranges loosely
52
53         -p --include-prerelease
54                 Always include prerelease versions in range matching
55
56         -c --coerce
57                 Coerce a string into SemVer if possible
58                 (does not imply --loose)
59
60         Program exits successfully if any valid version satisfies
61         all supplied ranges, and prints all satisfying versions.
62
63         If no satisfying versions are found, then exits failure.
64
65         Versions are printed in ascending order, so supplying
66         multiple versions to the utility will just sort them.
67

Versions

69       A   "version"  is  described  by  the  v2.0.0  specification  found  at
70       https://semver.org/.
71
72       A leading "=" or "v" character is stripped off and ignored.
73

Ranges

75       A version range is a set of comparators  which  specify  versions  that
76       satisfy the range.
77
78       A  comparator  is  composed  of  an operator and a version.  The set of
79       primitive operators is:
80
81       · < Less than
82
83       · <= Less than or equal to
84
85       · > Greater than
86
87       · >= Greater than or equal to
88
89       · = Equal.  If no operator is specified, then equality is  assumed,  so
90         this operator is optional, but MAY be included.
91
92
93       For  example,  the  comparator  >=1.2.7 would match the versions 1.2.7,
94       1.2.8, 2.5.3, and 1.3.9, but not the versions 1.2.6 or 1.1.0.
95
96       Comparators can be joined by whitespace to form a comparator set, which
97       is satisfied by the intersection of all of the comparators it includes.
98
99       A  range  is  composed of one or more comparator sets, joined by ||.  A
100       version matches a range if and only if every comparator in at least one
101       of the ||-separated comparator sets is satisfied by the version.
102
103       For  example,  the range >=1.2.7 <1.3.0 would match the versions 1.2.7,
104       1.2.8, and 1.2.99, but not the versions 1.2.6, 1.3.0, or 1.1.0.
105
106       The range 1.2.7 || >=1.2.9  <2.0.0  would  match  the  versions  1.2.7,
107       1.2.9, and 1.4.6, but not the versions 1.2.8 or 2.0.0.
108
109   Prerelease Tags
110       If  a version has a prerelease tag (for example, 1.2.3-alpha.3) then it
111       will only be allowed to satisfy comparator sets if at  least  one  com‐
112       parator with the same [major, minor, patch] tuple also has a prerelease
113       tag.
114
115       For example, the range >1.2.3-alpha.3 would be  allowed  to  match  the
116       version  1.2.3-alpha.7, but it would not be satisfied by 3.4.5-alpha.9,
117       even though 3.4.5-alpha.9 is technically "greater  than"  1.2.3-alpha.3
118       according  to  the  SemVer  sort rules.  The version range only accepts
119       prerelease tags on the 1.2.3 version.  The version 3.4.5 would  satisfy
120       the  range,  because  it  does not have a prerelease flag, and 3.4.5 is
121       greater than 1.2.3-alpha.7.
122
123       The purpose for this behavior is twofold.  First,  prerelease  versions
124       frequently  are updated very quickly, and contain many breaking changes
125       that are (by the author's design) not yet fit for  public  consumption.
126       Therefore, by default, they are excluded from range matching semantics.
127
128       Second,  a  user  who  has  opted  into  using a prerelease version has
129       clearly indicated the intent to use that specific set of  alpha/beta/rc
130       versions.   By  including  a  prerelease  tag in the range, the user is
131       indicating that they are aware of the risk.  However, it is  still  not
132       appropriate  to  assume that they have opted into taking a similar risk
133       on the next set of prerelease versions.
134
135       Note that this behavior can be suppressed (treating all prerelease ver‐
136       sions  as if they were normal versions, for the purpose of range match‐
137       ing) by setting the includePrerelease flag on the options object to any
138       functions  https://github.com/npm/node-semver#functions  that  do range
139       matching.
140
141   Prerelease Identifiers
142       The method .inc takes an additional  identifier  string  argument  that
143       will append the value of the string as a prerelease identifier:
144
145         semver.inc('1.2.3', 'prerelease', 'beta')
146         // '1.2.4-beta.0'
147
148       command-line example:
149
150         $ semver 1.2.3 -i prerelease --preid beta
151         1.2.4-beta.0
152
153       Which then can be used to increment further:
154
155         $ semver 1.2.4-beta.0 -i prerelease
156         1.2.4-beta.1
157
158   Advanced Range Syntax
159       Advanced  range syntax desugars to primitive comparators in determinis‐
160       tic ways.
161
162       Advanced ranges may be combined in the same way as  primitive  compara‐
163       tors using white space or ||.
164
165   Hyphen Ranges X.Y.Z - A.B.C
166       Specifies an inclusive set.
167
168       · 1.2.3 - 2.3.4 := >=1.2.3 <=2.3.4
169
170
171       If  a partial version is provided as the first version in the inclusive
172       range, then the missing pieces are replaced with zeroes.
173
174       · 1.2 - 2.3.4 := >=1.2.0 <=2.3.4
175
176
177       If a partial version is provided as the second version in the inclusive
178       range,  then  all  versions  that  start with the supplied parts of the
179       tuple are accepted, but nothing that would be greater than the provided
180       tuple parts.
181
182       · 1.2.3 - 2.3 := >=1.2.3 <2.4.0
183
184       · 1.2.3 - 2 := >=1.2.3 <3.0.0
185
186
187   X-Ranges 1.2.x 1.X 1.2.* *
188       Any of X, x, or * may be used to "stand in" for one of the numeric val‐
189       ues in the [major, minor, patch] tuple.
190
191       · * := >=0.0.0 (Any version satisfies)
192
193       · 1.x := >=1.0.0 <2.0.0 (Matching major version)
194
195       · 1.2.x := >=1.2.0 <1.3.0 (Matching major and minor versions)
196
197
198       A partial version range is treated as an X-Range, so the special  char‐
199       acter is in fact optional.
200
201       · "" (empty string) := * := >=0.0.0
202
203       · 1 := 1.x.x := >=1.0.0 <2.0.0
204
205       · 1.2 := 1.2.x := >=1.2.0 <1.3.0
206
207
208   Tilde Ranges ~1.2.3 ~1.2 ~1
209       Allows  patch-level changes if a minor version is specified on the com‐
210       parator.  Allows minor-level changes if not.
211
212       · ~1.2.3 := >=1.2.3 <1.(2+1).0 := >=1.2.3 <1.3.0
213
214       · ~1.2 := >=1.2.0 <1.(2+1).0 := >=1.2.0 <1.3.0 (Same as 1.2.x)
215
216       · ~1 := >=1.0.0 <(1+1).0.0 := >=1.0.0 <2.0.0 (Same as 1.x)
217
218       · ~0.2.3 := >=0.2.3 <0.(2+1).0 := >=0.2.3 <0.3.0
219
220       · ~0.2 := >=0.2.0 <0.(2+1).0 := >=0.2.0 <0.3.0 (Same as 0.2.x)
221
222       · ~0 := >=0.0.0 <(0+1).0.0 := >=0.0.0 <1.0.0 (Same as 0.x)
223
224       · ~1.2.3-beta.2 := >=1.2.3-beta.2 <1.3.0 Note that prereleases  in  the
225         1.2.3  version  will be allowed, if they are greater than or equal to
226         beta.2.  So, 1.2.3-beta.4 would be allowed,  but  1.2.4-beta.2  would
227         not,  because it is a prerelease of a different [major, minor, patch]
228         tuple.
229
230
231   Caret Ranges ^1.2.3 ^0.2.5 ^0.0.4
232       Allows changes that do not modify the left-most non-zero digit  in  the
233       [major,  minor,  patch]  tuple.   In other words, this allows patch and
234       minor updates for versions 1.0.0 and above, patch updates for  versions
235       0.X >=0.1.0, and no updates for versions 0.0.X.
236
237       Many  authors  treat  a  0.x version as if the x were the major "break‐
238       ing-change" indicator.
239
240       Caret ranges are ideal when an author may make breaking changes between
241       0.2.4 and 0.3.0 releases, which is a common practice.  However, it pre‐
242       sumes that there will not be breaking changes between 0.2.4 and  0.2.5.
243       It  allows for changes that are presumed to be additive (but non-break‐
244       ing), according to commonly observed practices.
245
246       · ^1.2.3 := >=1.2.3 <2.0.0
247
248       · ^0.2.3 := >=0.2.3 <0.3.0
249
250       · ^0.0.3 := >=0.0.3 <0.0.4
251
252       · ^1.2.3-beta.2 := >=1.2.3-beta.2 <2.0.0 Note that prereleases  in  the
253         1.2.3  version  will be allowed, if they are greater than or equal to
254         beta.2.  So, 1.2.3-beta.4 would be allowed,  but  1.2.4-beta.2  would
255         not,  because it is a prerelease of a different [major, minor, patch]
256         tuple.
257
258       · ^0.0.3-beta := >=0.0.3-beta <0.0.4   Note  that  prereleases  in  the
259         0.0.3 version only will be allowed, if they are greater than or equal
260         to beta.  So, 0.0.3-pr.2 would be allowed.
261
262
263       When parsing caret ranges, a missing patch value desugars to the number
264       0,  but will allow flexibility within that value, even if the major and
265       minor versions are both 0.
266
267       · ^1.2.x := >=1.2.0 <2.0.0
268
269       · ^0.0.x := >=0.0.0 <0.1.0
270
271       · ^0.0 := >=0.0.0 <0.1.0
272
273
274       A missing minor and patch values will desugar to zero, but  also  allow
275       flexibility within those values, even if the major version is zero.
276
277       · ^1.x := >=1.0.0 <2.0.0
278
279       · ^0.x := >=0.0.0 <1.0.0
280
281
282   Range Grammar
283       Putting  all  this  together, here is a Backus-Naur grammar for ranges,
284       for the benefit of parser authors:
285
286         range-set  ::= range ( logical-or range ) *
287         logical-or ::= ( ' ' ) * '||' ( ' ' ) *
288         range      ::= hyphen | simple ( ' ' simple ) * | ''
289         hyphen     ::= partial ' - ' partial
290         simple     ::= primitive | partial | tilde | caret
291         primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
292         partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
293         xr         ::= 'x' | 'X' | '*' | nr
294         nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
295         tilde      ::= '~' partial
296         caret      ::= '^' partial
297         qualifier  ::= ( '-' pre )? ( '+' build )?
298         pre        ::= parts
299         build      ::= parts
300         parts      ::= part ( '.' part ) *
301         part       ::= nr | [-0-9A-Za-z]+
302

Functions

304       All methods and classes take a  final  options  object  argument.   All
305       options  in  this  object  are false by default.  The options supported
306       are:
307
308       · loose  Be more forgiving about not-quite-valid semver strings.   (Any
309         resulting  output  will  always be 100% strict compliant, of course.)
310         For backwards compatibility reasons, if the  options  argument  is  a
311         boolean value instead of an object, it is interpreted to be the loose
312         param.
313
314       · includePrerelease    Set   to   suppress   the    default    behavior
315         https://github.com/npm/node-semver#prerelease-tags  of excluding pre‐
316         release tagged versions from ranges unless they are explicitly  opted
317         into.
318
319
320       Strict-mode  Comparators  and  Ranges  will  be strict about the SemVer
321       strings that they parse.
322
323       · valid(v): Return the parsed version, or null if it's not valid.
324
325       · inc(v, release): Return the version incremented by the  release  type
326         (major,   premajor, minor, preminor, patch, prepatch, or prerelease),
327         or null if it's not valid
328
329         · premajor in one call will bump the version up  to  the  next  major
330           version  and down to a prerelease of that major version.  preminor,
331           and prepatch work the same way.
332
333         · If called from a non-prerelease version, the prerelease  will  work
334           the same as prepatch. It increments the patch version, then makes a
335           prerelease. If the input version is already a prerelease it  simply
336           increments it.
337
338
339       · prerelease(v):  Returns an array of prerelease components, or null if
340         none exist. Example: prerelease('1.2.3-alpha.1') -> ['alpha', 1]
341
342       · major(v): Return the major version number.
343
344       · minor(v): Return the minor version number.
345
346       · patch(v): Return the patch version number.
347
348       · intersects(r1, r2, loose): Return true if the two supplied ranges  or
349         comparators intersect.
350
351       · parse(v):  Attempt to parse a string as a semantic version, returning
352         either a SemVer object or null.
353
354
355   Comparison
356       · gt(v1, v2): v1 > v2
357
358       · gte(v1, v2): v1 >= v2
359
360       · lt(v1, v2): v1 < v2
361
362       · lte(v1, v2): v1 <= v2
363
364       · eq(v1, v2): v1 == v2 This is true if  they're  logically  equivalent,
365         even  if  they're not the exact same string.  You already know how to
366         compare strings.
367
368       · neq(v1, v2): v1 != v2 The opposite of eq.
369
370       · cmp(v1, comparator, v2): Pass in a comparison string, and it'll  call
371         the  corresponding  function above.  "===" and "!==" do simple string
372         comparison, but are included for completeness.  Throws if an  invalid
373         comparison string is provided.
374
375       · compare(v1,  v2):  Return 0 if v1 == v2, or 1 if v1 is greater, or -1
376         if  v2  is  greater.   Sorts  in  ascending  order   if   passed   to
377         Array.sort().
378
379       · rcompare(v1, v2): The reverse of compare.  Sorts an array of versions
380         in descending order when passed to Array.sort().
381
382       · diff(v1, v2): Returns difference between two versions by the  release
383         type  (major,  premajor,  minor, preminor, patch, prepatch, or prere‐
384         lease), or null if the versions are the same.
385
386
387   Comparators
388       · intersects(comparator): Return true if the comparators intersect
389
390
391   Ranges
392       · validRange(range): Return the valid range or null if it's not valid
393
394       · satisfies(version, range): Return true if the version  satisfies  the
395         range.
396
397       · maxSatisfying(versions,  range):  Return  the  highest version in the
398         list that satisfies the range, or null if none of them do.
399
400       · minSatisfying(versions, range): Return the lowest version in the list
401         that satisfies the range, or null if none of them do.
402
403       · minVersion(range):  Return the lowest version that can possibly match
404         the given range.
405
406       · gtr(version, range): Return true if version is greater than  all  the
407         versions possible in the range.
408
409       · ltr(version, range): Return true if version is less than all the ver‐
410         sions possible in the range.
411
412       · outside(version, range, hilo): Return true if the version is  outside
413         the  bounds  of  the  range in either the high or low direction.  The
414         hilo argument must be either the string '>' or  '<'.   (This  is  the
415         function called by gtr and ltr.)
416
417       · intersects(range):  Return  true  if  any  of  the ranges comparators
418         intersect
419
420
421       Note that, since ranges may be non-contiguous, a version might  not  be
422       greater than a range, less than a range, or satisfy a range!  For exam‐
423       ple, the range 1.2 <1.2.9 || >2.0.0 would have a hole from 1.2.9  until
424       2.0.0,  so  the  version  1.2.10  would  not  be greater than the range
425       (because 2.0.1 satisfies, which is higher), nor  less  than  the  range
426       (since  1.2.8  satisfies, which is lower), and it also does not satisfy
427       the range.
428
429       If you want to know if a version satisfies or does not satisfy a range,
430       use the satisfies(version, range) function.
431
432   Coercion
433       · coerce(version): Coerces a string to semver if possible
434
435
436       This  aims  to  provide  a  very  forgiving translation of a non-semver
437       string to semver. It looks for the first digit in a  string,  and  con‐
438       sumes  all remaining characters which satisfy at least a partial semver
439       (e.g., 1, 1.2, 1.2.3) up to the max permitted length (256  characters).
440       Longer  versions are simply truncated (4.6.3.9.2-alpha2 becomes 4.6.3).
441       All surrounding text is simply ignored (v3.4  replaces  v3.3.1  becomes
442       3.4.0).   Only  text which lacks digits will fail coercion (version one
443       is not valid).  The maximum  length for any semver component considered
444       for  coercion  is  16  characters;  longer  components  will be ignored
445       (10000000000000000.4.7.4 becomes 4.7.4).  The  maximum  value  for  any
446       semver  component  is  Number.MAX_SAFE_INTEGER  ||  (2**53 - 1); higher
447       value  components  are  invalid   (9999999999999999.4.7.4   is   likely
448       invalid).
449
450
451
452                                 February 2021                       SEMVER(7)
Impressum