NPM Version Ranges - Quick Reference

npm-version-ranges.md

NPM Version Ranges - Quick Reference

Quick Reference Cheat Sheet

Symbol	Name	Update Level	Example	Matches	Won't Match
^	Caret	Minor + Patch	^1.2.3	1.2.3, 1.9.0	2.0.0
~	Tilde	Patch only	~1.2.3	1.2.3, 1.2.9	1.3.0
(none)	Exact	None	1.2.3	1.2.3 only	1.2.4
* or x	Wildcard	Everything	1.x	1.0.0, 1.9.9	2.0.0
> < >= <=	Comparisons	Custom range	>=1.2.0 <2.0.0	1.2.0 to 1.9.9	2.0.0
-	Hyphen range	Inclusive range	1.2.3 - 2.0.0	1.2.3 to 2.0.0	2.0.1
||	OR	Multiple ranges	^1.0.0 || ^2.0.0	1.x.x or 2.x.x	3.0.0

Best Practices

By Project Type

Scenario	Recommended Range	Reason
Application dependencies	^ (caret)	Get security fixes and features automatically
Library dependencies	^ with peerDependencies	Allow flexibility for library consumers
Critical production apps	~ (tilde) or exact	Maximum stability, controlled updates
Experimental/internal tools	latest or *	Always cutting edge

Common Patterns

Conservative (Most Stable)

{
  "dependencies": {
    "react": "18.2.0",           // exact version - no auto-updates
    "lodash": "~4.17.21"         // only patch updates (bug fixes)
  }
}

Balanced (NPM Default - Recommended)

{
  "dependencies": {
    "react": "^18.2.0",          // minor + patch updates
    "express": "^4.18.2"         // new features + bug fixes
  }
}

Aggressive (Risky)

{
  "dependencies": {
    "react": "*",                // any version - NOT recommended
    "express": ">=4.0.0"         // any 4.x or higher
  }
}

Common Examples

Caret ^ - Default Behavior

"^1.2.3"   // Matches: 1.2.3, 1.2.4, 1.9.0, 1.999.999  |  Blocks: 2.0.0
"^0.2.3"   // Matches: 0.2.3, 0.2.4, 0.2.999           |  Blocks: 0.3.0
"^0.0.3"   // Matches: 0.0.3 only                      |  Blocks: 0.0.4

Logic: Trust updates that don't change the left-most non-zero digit

Tilde ~ - Conservative

"~1.2.3"   // Matches: 1.2.3, 1.2.4, 1.2.999           |  Blocks: 1.3.0
"~1.2"     // Matches: 1.2.0, 1.2.999                  |  Blocks: 1.3.0
"~1"       // Matches: 1.0.0, 1.999.999                |  Blocks: 2.0.0

Logic: Only accept patch-level changes (bug fixes)

Updating Dependencies

Check for updates

npm outdated

Update within current range

npm update

Update to latest (ignoring semver range)

npm install react@latest

Update multiple packages

npm install react@latest react-dom@latest eslint@latest

Use npm-check-updates (recommended)

# Install globally
npm install -g npm-check-updates

# See what would update
ncu

# Update package.json to latest
ncu -u

# Install new versions
npm install

Understanding npm outdated Output

Package    Current   Wanted   Latest
react      19.1.0    19.1.0   19.2.4

• Current: What's installed now
• Wanted: Latest version matching your package.json range
• Latest: Absolute latest version (may require updating package.json)

If Current = Wanted, then npm update won't do anything. You need to manually update the range in package.json.

Special Cases

Pre-release versions

"^1.2.3"        // Won't match: 1.2.4-beta.1
"^1.2.3-beta"   // Will match: 1.2.3-beta.2, 1.2.3-rc.1

Tags (avoid in production)

"latest"   // Latest stable release (changes over time!)
"next"     // Beta/next release channel

Tips

1. Always commit package-lock.json - ensures everyone gets the same versions
2. Use ^ for most dependencies - balances stability with security updates
3. Use ~ or exact for critical dependencies - when you need maximum control
4. Audit regularly - npm audit to check for security issues
5. Test after updates - especially major version bumps (e.g., 9.x.x → 10.0.0)

Quick Commands

# Lock to exact version
npm install react@19.2.4 --save-exact

# Update to specific range
npm install react@^19.2.4

# Update all dependencies (respecting ranges)
npm update

# Update all to latest (breaking changes possible)
ncu -u && npm install

---

Remember: Semver is MAJOR.MINOR.PATCH

• MAJOR: Breaking changes
• MINOR: New features (backwards compatible)
• PATCH: Bug fixes (backwards compatible)