# semver (JavaScript) — card for AI agents

Parser and utilities for semantic versioning, widely used across Node.js ecosystems.

Category: Utilities · npm package `semver` · latest version 7.8.5 (checked 2026-11-01)
Install: `npm install semver`
License: ISC (permissive)

In your own product (generator, app, hosted service): **yes**. Permissive license: ship it inside your own product, closed or open source, and keep its license and copyright notice.

## Numbers (AgentGid data)
- Gid Score: 69.3 (#370 of all tools, 38 of 406 in its category)
- Used in 64 public projects set up for AI coding agents (1.0%)
- Downloads last week: 1,187,753,782 (as of 2026-11-17), +17.5% over 4 weeks
- GitHub stars: 5,475 (as of 2026-11-17)
- Last push: 2026-11-05

## Often used with
Vitest 70.3%, tsx 54.7%, yaml 45.3%, chalk 42.2%, esbuild 42.2%, ws 40.6%

## Links
- AgentGid page: https://agentgid.com/tools/semver-npm/
- Homepage: https://github.com/npm/node-semver#readme
- Repository: https://github.com/npm/node-semver


## semver: compare and bump version numbers in JavaScript

semver is a small free JavaScript library that understands version numbers like 1.4.2 and rules like "1.2 or newer, but not 2". Your app or script can tell which version is newer, whether a version fits a rule, and what the next version number should be. It is the same version logic npm itself uses.

### Where to use it
- Stop when Node.js is too old: Your setup script checks the installed Node.js version first and stops with a clear message instead of failing later.
- Tell users an update is out: Your tool compares its own version with the newest one and says whether the update is a big or a small change.
- Pick the newest version that fits: From a list of published versions, choose the highest one that still matches the rule in your settings file.
- Work out the next release number: Before you publish, your release script computes the next patch, minor, major or beta number from the current one.
- Read versions from messy text: Pull a usable version out of strings like "v3.4 replaces v3.3.1" that other tools print.
- Check which plugins fit your app: Each plugin states the app versions it supports; your app loads only the plugins whose rule matches its own version. (idea, not from the official pages)

### How to start
- Add semver to your project.

```
npm install semver
```

- Load it and call the function you need.

```
const semver = require('semver')

semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
```


### License
Free for any use, paid or not, under the ISC license. Keep the short license notice with copies of the library; no credit on screen is needed.

### Good to know
- Beta and release-candidate versions are skipped by version rules unless you ask for them.
- For versions starting with 0, the caret rule ^0.2.3 allows only 0.2.x updates, not 0.3.0.
- The forgiving reader keeps only the first three numbers, so 4.6.3.9.2 becomes 4.6.3.
- It runs on Node.js 10 or newer.

Checked 2026-11-10 against: https://github.com/npm/node-semver/blob/main/README.md, https://github.com/npm/node-semver/blob/main/LICENSE, https://github.com/npm/node-semver/blob/main/CHANGELOG.md, https://registry.npmjs.org/semver/7.8.6, https://registry.npmjs.org/semver, https://semver.org/, https://docs.npmjs.com/about-semantic-versioning, https://docs.npmjs.com/cli/v11/configuring-npm/package-json

### Mistakes to avoid
- Don't: if (latest > current) with version strings → Do: semver.gt(latest, current) or semver.compare(a, b) (Plain string comparison says "1.10.0" > "1.9.0" is false (our run); semver compares the numbers.)
- Don't: semver.satisfies("1.9.0-beta.1", "^1.2.0") and expecting true → Do: semver.satisfies(v, range, { includePrerelease: true }) when betas should count (Pre-releases are excluded from ranges by default; in our run the beta matched only with the flag.)
- Don't: Writing ^0.2.3 and expecting 0.3.0 to be accepted → Do: Use >=0.2.3 <1.0.0 if you really want every 0.x update (For 0.x versions the caret rule only allows patch updates.)
- Don't: semver.clean("~1.0.0") or semver.valid("1.4") → Do: semver.validRange("~1.0.0") for rules; semver.valid(semver.coerce("1.4")) for partial versions (clean() and valid() accept only full single versions; both returned null in our run.)

### Questions
- What does a version number like 2.1.0 mean? Under Semantic Versioning the first number goes up for breaking changes, the second for new features, the third for fixes.
- Does it accept versions written as v1.2.3? Yes. A leading v or = is stripped before the version is read.
- Why does 1.9.0-beta.1 not match ^1.2.0? Pre-release versions are left out of rules by default; pass { includePrerelease: true } to count them.
- Can it clean up a rule like ~1.0.0? No. clean() works only on single versions; for rules use validRange().

---
AgentGid's catalog is curated: every entry was checked against the maker's official pages (registry, repository, license and pricing pages) on the date shown; a license value shows the quote it stands on wherever AgentGid has one. Usage numbers come from AgentGid's own scan of public repositories set up for AI coding agents. Claims by makers are reported, not tested by AgentGid.
