npm: Caret (^) vs Tilde (~) — Which to Choose?

Caret vs Tilde in npm — A Practical Guide

Both ^ and ~ are range operators, but they control how aggressively your dependencies can update. Here is a direct comparison.

Side-by-Side Comparison

Aspect	Caret (^)	Tilde (~)
Default	Yes (npm install)	No (manual)
Updates allowed	Minor + Patch	Patch only
Risk level	Moderate	Low
New features	Yes	No
^1.2.3 range	>=1.2.3 <2.0.0	N/A
~1.2.3 range	N/A	>=1.2.3 <1.3.0

Decision Matrix

Use caret (^) when:

• ✅ The library follows SemVer strictly
• ✅ You want to get new features automatically
• ✅ You have good test coverage to catch regressions
• ✅ It is a development dependency (testing, linting)

Use tilde (~) when:

• ✅ Stability is more important than features
• ✅ The library has a history of breaking changes in minor versions
• ✅ It is a production-critical dependency
• ✅ You want only bug fixes, no surprises

Real-World Example

{
  "dependencies": {
    "express": "^4.18.0",
    "pg": "~8.11.0"
  },
  "devDependencies": {
    "jest": "^29.7.0",
    "typescript": "~5.3.0"
  }
}

In this setup:

• express uses caret — we trust Express to follow SemVer
• pg uses tilde — database drivers need extra stability
• jest uses caret — test tools can update freely
• typescript uses tilde — compiler changes can break builds

The Lock File Safety Net

Both ranges work together with package-lock.json (npm) or yarn.lock. The lock file pins the exact installed version, and ranges only matter during npm update or fresh npm install without a lock file.