Documentation Index
Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
Use this file to discover all available pages before exploring further.
Override package versions in your dependency tree.
What are overrides?
Overrides allow you to replace package versions anywhere in your dependency tree, even if they’re transitive dependencies (dependencies of dependencies).
Configuration
In package.json
{
"overrides": {
"lodash": "4.17.21"
}
}
lodash with version 4.17.21.
Nested overrides
Override dependencies of specific packages:
{
"overrides": {
"foo": {
"bar": "1.0.0"
}
}
}
bar only when it’s a dependency of foo.
Deep nested overrides
{
"overrides": {
"foo": {
"bar": {
"baz": "2.0.0"
}
}
}
}
baz only when it’s: foo → bar → baz
Use cases
Security patches
Force a security patch for a transitive dependency:
{
"dependencies": {
"some-package": "^1.0.0"
},
"overrides": {
"minimist": "^1.2.6"
}
}
some-package depends on an older minimist, Bun installs 1.2.6.
Fix bugs
Override buggy transitive dependencies:
{
"overrides": {
"node-fetch": "2.6.7"
}
}
Force specific versions
Ensure consistent versions across dependencies:
{
"dependencies": {
"react-library-a": "^1.0.0",
"react-library-b": "^2.0.0"
},
"overrides": {
"react": "18.2.0"
}
}
Replace unmaintained packages
{
"overrides": {
"old-package": "npm:new-package@^2.0.0"
}
}
Syntax
Exact version
{
"overrides": {
"lodash": "4.17.21"
}
}
Version range
{
"overrides": {
"lodash": "^4.17.0"
}
}
Package alias
{
"overrides": {
"old-lib": "npm:new-lib@^1.0.0"
}
}
All versions
{
"overrides": {
"lodash": "*"
}
}
Reference parent version
{
"dependencies": {
"react": "^18.2.0"
},
"overrides": {
"react": "$react"
}
}
dependencies.
Scoped overrides
Override for specific parent
{
"overrides": {
"package-a": {
"lodash": "4.17.21"
}
}
}
lodash only when it’s a dependency of package-a.
Multiple levels
{
"overrides": {
"package-a": {
"package-b": {
"lodash": "4.17.21"
}
}
}
}
lodash only in the chain: package-a → package-b → lodash
Wildcard parent
{
"overrides": {
"*": {
"lodash": "4.17.21"
}
}
}
Examples
Security fix
{
"name": "my-app",
"dependencies": {
"express": "^4.17.0"
},
"overrides": {
"qs": "6.11.0"
}
}
$ bun install
Warning: Overriding qs@6.9.0 with 6.11.0
+ 57 packages installed [892ms]
Deduplicate React versions
{
"dependencies": {
"react-router": "^6.0.0",
"react-query": "^3.0.0"
},
"overrides": {
"react": "18.2.0",
"react-dom": "18.2.0"
}
}
Fix peer dependency conflicts
{
"dependencies": {
"library-a": "^1.0.0",
"library-b": "^2.0.0"
},
"overrides": {
"library-a": {
"peer-dep": "^2.0.0"
}
}
}
Replace deprecated package
{
"overrides": {
"request": "npm:node-fetch@^3.0.0"
}
}
request now use node-fetch.
Comparison with resolutions
Yarn resolutions
Yarn uses resolutions field:
{
"resolutions": {
"lodash": "4.17.21"
}
}
overrides and resolutions for compatibility.
npm overrides
Bun’s overrides syntax is compatible with npm 8.3+:
{
"overrides": {
"lodash": "4.17.21"
}
}
pnpm overrides
pnpm uses pnpm.overrides:
{
"pnpm": {
"overrides": {
"lodash": "4.17.21"
}
}
}
pnpm.overrides when migrating from pnpm.
Verification
Check overrides are applied
After installing:
$ bun pm ls lodash
lodash@4.17.21 (overridden from 4.17.20)
├── some-package@1.0.0
│ └── lodash@4.17.21
└── other-package@2.0.0
└── lodash@4.17.21
View dependency tree
Verify all instances use the override version.
Warnings
Version conflicts
Bun warns about overrides that might break compatibility:
$ bun install
Warning: Overriding lodash@4.17.20 with 3.10.0
This may cause compatibility issues with some-package@1.0.0
+ 134 packages installed
Missing overrides
If an override doesn’t match any packages:
$ bun install
Warning: Override for "non-existent-package" did not match any packages
+ 134 packages installed
Troubleshooting
Override not applied
Check:
- Package name - Must match exactly
- Version exists - Verify version exists in registry
- Syntax - Validate JSON syntax
# Verify package exists
bun pm view lodash@4.17.21
Lockfile out of sync
After adding overrides:
Check what was overridden
bun pm ls | grep "(overridden"
Best practices
Document overrides
Add comments explaining why:
{
"overrides": {
// Security fix for CVE-2021-12345
"lodash": "4.17.21",
// Bug fix until upstream updates
"axios": "0.27.2"
}
}
Be specific
Use scoped overrides when possible:
{
"overrides": {
// Only override for package-a
"package-a": {
"lodash": "4.17.21"
}
}
}
Test thoroughly
Overrides can break functionality:
Review periodically
Remove overrides when upstream packages update:
# Check if override is still needed
bun outdated
Use with caution
Overrides bypass package manager resolution. Only use when necessary.
Advanced patterns
Conditional overrides
Different overrides per environment:
// package.json (development)
{
"overrides": {
"debug": "^4.0.0"
}
}
// package.production.json
{
"overrides": {
"debug": "^3.0.0"
}
}
Multiple package versions
{
"overrides": {
"package-v1": "npm:package@^1.0.0",
"package-v2": "npm:package@^2.0.0"
}
}
Override transitive peer dependencies
{
"overrides": {
"*": {
"@types/react": "18.0.0"
}
}
}
Catalogs
For managing shared versions across workspaces, see catalogs.
Patches
For patching package code, see bun patch command.
Resolutions
Bun supports Yarn’s resolutions field for compatibility:
{
"resolutions": {
"lodash": "4.17.21"
}
}
