compare-versions

Install the package using npm to use it in Node.js, React Native, or bundler-based web projects.

Note on Imports:

• Since v5, the main export is a named export: import { compareVersions } from 'compare-versions'.
• Since v4, the library includes an ESM version that bundlers like Webpack or Parcel will automatically select. The CJS/UMD version is located at lib/umd/index.js and the ESM version at lib/esm/index.js.

$ npm install compare-versions

You can use the library in a browser environment using either ES Modules or the legacy UMD global object.

ES Modules (Modern Browsers): Import directly from the ESM build path.

UMD (Legacy/Direct Script): Include the script via a CDN (like unpkg) and access the functions via window.compareVersions.

<!-- ES Modules approach -->
<script type="module">
  import { compareVersions, compare, satisfies, validate, validateStrict } from './node_modules/compare-versions/lib/esm/index.js'
  console.log(compareVersions('11.0.0', '10.0.0'))
</script>

<!-- UMD approach -->
<script src="https://unpkg.com/compare-versions/lib/umd/index.js"></script>
<script>
  const { compareVersions, compare, satisfies, validate, validateStrict } = window.compareVersions
  console.log(compareVersions('11.0.0', '10.0.0'))
</script>

The satisfies function checks if a version string meets a specific range, compatible with npm version ranges.

import { satisfies } from 'compare-versions';

satisfies('10.0.1', '~10.0.0');  // true
satisfies('10.1.0', '~10.0.0');  // false
satisfies('10.1.2', '^10.0.0');  // true
satisfies('11.0.0', '^10.0.0');  // false
satisfies('10.1.8', '>10.0.4');  // true
satisfies('10.0.1', '=10.0.1');  // true
satisfies('10.1.1', '<10.2.2');  // true
satisfies('10.1.1', '<=10.2.2'); // true
satisfies('10.1.1', '>=10.2.2'); // false
satisfies('1.4.6', '1.2.7 || >=1.2.9 <2.0.0'); // true
satisfies('1.2.8', '1.2.7 || >=1.2.9 <2.0.0'); // false
satisfies('1.5.1', '1.2.3 - 2.3.4'); // true
satisfies('2.3.5', '1.2.3 - 2.3.4'); // false

The compare function allows you to compare two versions using a human-friendly operator string. It returns a boolean.

Supported operators include: >, =, <, <=, >=.

import { compare } from 'compare-versions';

compare('10.1.8', '10.0.4', '>');  // true
compare('10.0.1', '10.0.1', '=');  // true
compare('10.1.1', '10.2.2', '<');  // true
compare('10.1.1', '10.2.2', '<='); // true
compare('10.1.1', '10.2.2', '>='); // false

Use validate for flexible version checking (allowing wildcards, leading 'v', etc.) or validateStrict for strict adherence to the semver.org specification.

validate(version): Returns true if the version follows the comparison rules used by the library. validateStrict(version): Returns true only if the version is strictly semver (3 integers, no wildcards, no leading zeros, no leading 'v').

import { validate, validateStrict } from 'compare-versions';

// Flexible validation
validate('1.0.0-rc.1'); // true
validate('1.0-rc.1');   // false
validate('foo');        // false

// Strict validation
validateStrict('1.0.0');      // true
validateStrict('1.0.0-rc.1'); // true
validateStrict('1.0');        // false
validateStrict('1.x');        // false
validateStrict('v1.02');     // false

The compareVersions function compares two semver version strings. It returns:

• 1 if the first version is greater.
• 0 if the versions are equal.
• -1 if the second version is greater.

It supports full semver (including pre-releases like 1.0.0-alpha), wildcards (1.0.x), Chromium-style 4-part versions (25.0.1364.126), and ignores leading v or leading zeros.

import { compareVersions } from 'compare-versions';

compareVersions('11.1.1', '10.0.0'); //  1
compareVersions('10.0.0', '10.0.0'); //  0
compareVersions('10.0.0', '11.1.1'); // -1

// Usage for sorting arrays
const versions = ['1.5.19', '1.2.3', '1.5.5'];
const sorted = versions.sort(compareVersions);
// Result: ['1.2.3', '1.5.5', '1.5.19']

Use compareVersions to compare two version strings. It returns a string representing the comparison result.

import { compareVersions } from 'compare-versions';

// Returns '>', '<', or '=='
const result = compareVersions('1.2.3', '1.2.2');

Use validateStrict(version) for rigorous validation of semver strings. Unlike validate(), this function will not accept wildcards or version ranges; it only returns true for exact, fully-qualified semver strings that match the official specification.

// Example of strict validation behavior
validateStrict('1.0.0-rc.1'); // return true
// Note: validateStrict is designed to reject ranges/wildcards that validate() might accept

Use validate for standard version validation or validateStrict for more rigorous checks to ensure a string is a valid version number.

import { validate, validateStrict } from 'compare-versions';

const isValid = validate('1.2.3');
const isStrictlyValid = validateStrict('1.2.3');

Use validate(version) to check if a string is a valid Semantic Versioning (semver) string. This function accepts standard semver formats, including those with pre-release tags or build metadata. It returns true if the version is valid and false otherwise.

validate('1.0.0-rc.1'); // return true
validate('1.0-rc.1'); // return false
validate('foo'); // return false

Use compare to compare two version strings. It returns a number indicating the relationship between the versions.

import { compare } from 'compare-versions';

// Returns 1 if v1 > v2, -1 if v1 < v2, or 0 if v1 === v2
const result = compare('1.2.3', '1.2.2');