^ vs ~
If you’ve ever looked at a package.json and wondered:
"lodash": "^4.17.21"
…or maybe:
"express": "~4.18.2"
And thought what’s with the hat and the squiggly line?, you’re not alone. Let’s decode what these characters do, and when to use them.
🔍 TL;DR: What do ^ and ~ mean in package.json?
| Symbol | Allows Updates To | Example | Can Upgrade To |
|---|---|---|---|
^ | Minor & Patch | ^1.2.3 | 1.3.0, 1.2.4 |
~ | Patch only | ~1.2.3 | 1.2.4, not 1.3 |
| none | Exact version | 1.2.3 | Only 1.2.3 |
^ (Caret)
The caret means:
«Install this version or anything newer that doesn’t break major version compatibility.»
This follows Semantic Versioning (SemVer), where a major.minor.patch version tells you the scope of the changes.
Example:
"axios": "^1.3.2"
Can update to:
- ✅
1.3.3 - ✅
1.9.9 - ❌
2.0.0(major version change)
📌 It’s the default versioning npm uses when you run npm install axios@1.3.2.
~ (Tilde)
The tilde means:
«Install this version or any newer patch within the same minor version.»
Example:
"axios": "~1.3.2"
Can update to:
- ✅
1.3.3 - ✅
1.3.9 - ❌
1.4.0
This is much more conservative — perfect for when you don’t want unexpected changes sneaking into your builds.
🔥 Why This Matters: The Hidden Danger
Imagine this:
- You deploy your app today with
^1.3.2. - A week later,
1.4.0is released with a subtle change that breaks your edge case. - You run
npm install, and suddenly your app is acting weird.
Surprise! 🎉
Unless you locked dependencies or used ~, you’re getting updates whether you asked for them or not.
🧠 Pros and Cons
| Symbol | Pros | Cons |
|---|---|---|
^ | Keeps you up-to-date easily | Risk of breakage in minor updates |
~ | Safer and more predictable builds | Can miss out on minor improvements |
| none | Total control (exact version) | No updates unless manual |
🛠️ When to Use What?
Use ^ when:
- You’re building a library or want the latest stable versions
- You’re okay with minor version bumps and trust the maintainers
Use ~ when:
- Stability is critical (e.g. production apps)
- You want tight control over updates
- You’ve been burned before
Use no symbol when:
- You want full determinism
- You’re building dockerized / reproducible builds
📦 Bonus: How to Check What’s Actually Installed
To see what version was installed:
npm list <package-name>
An alternative to this is just checking your yarn.lock or package-lock.json
To find out what’s outdated:
npm outdated
🧵 Conclusion
Choosing between ^ and ~ might seem like a small detail, but it can mean the difference between a calm deploy and hours of debugging.
Use ^ if you like to live a little.
Use ~ if you like sleeping at night.
Use no symbol if you’re preparing for war ⚔️.