Overrides

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"
  }
}

This replaces all occurrences of lodash with version 4.17.21.

Nested overrides

Override dependencies of specific packages:

{
  "overrides": {
    "foo": {
      "bar": "1.0.0"
    }
  }
}

This overrides bar only when it’s a dependency of foo.

Deep nested overrides

{
  "overrides": {
    "foo": {
      "bar": {
        "baz": "2.0.0"
      }
    }
  }
}

Overrides 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"
  }
}

Even if 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"
  }
}

Both libraries use React 18.2.0, even if they specify different versions.

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": "*"
  }
}

Uses latest version.

Reference parent version

{
  "dependencies": {
    "react": "^18.2.0"
  },
  "overrides": {
    "react": "$react"
  }
}

Uses the version specified in dependencies.

Scoped overrides

Override for specific parent

{
  "overrides": {
    "package-a": {
      "lodash": "4.17.21"
    }
  }
}

Overrides lodash only when it’s a dependency of package-a.

Multiple levels

{
  "overrides": {
    "package-a": {
      "package-b": {
        "lodash": "4.17.21"
      }
    }
  }
}

Overrides lodash only in the chain: package-a → package-b → lodash

Wildcard parent

{
  "overrides": {
    "*": {
      "lodash": "4.17.21"
    }
  }
}

Same as global override.

Examples

Security fix

{
  "name": "my-app",
  "dependencies": {
    "express": "^4.17.0"
  },
  "overrides": {
    "qs": "6.11.0"
  }
}

Install:

$ bun install

Warning: Overriding [email protected] 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"
  }
}

All dependencies using request now use node-fetch.

Comparison with resolutions

Yarn resolutions

Yarn uses resolutions field:

{
  "resolutions": {
    "lodash": "4.17.21"
  }
}

Bun supports both 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"
    }
  }
}

Bun reads pnpm.overrides when migrating from pnpm.

Verification

Check overrides are applied

After installing:

$ bun pm ls lodash
[email protected] (overridden from 4.17.20)
├── [email protected]
│   └── [email protected]
└── [email protected]
    └── [email protected]

View dependency tree

bun pm ls --all

Verify all instances use the override version.

Warnings

Version conflicts

Bun warns about overrides that might break compatibility:

$ bun install

Warning: Overriding [email protected] with 3.10.0
This may cause compatibility issues with [email protected]

+ 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 [email protected]

Lockfile out of sync

After adding overrides:

rm bun.lockb
bun install

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:

bun install
bun test

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"
  }
}

Commands

Configuration

​What are overrides?

​Configuration

​In package.json

​Nested overrides

​Deep nested overrides

​Use cases

​Security patches

​Fix bugs

​Force specific versions

​Replace unmaintained packages

​Syntax

​Exact version

​Version range

​Package alias

​All versions

​Reference parent version

​Scoped overrides

​Override for specific parent

​Multiple levels

​Wildcard parent

​Examples

​Security fix

​Deduplicate React versions

​Fix peer dependency conflicts

​Replace deprecated package

​Comparison with resolutions

​Yarn resolutions

​npm overrides

​pnpm overrides

​Verification

​Check overrides are applied

​View dependency tree

​Warnings

​Version conflicts

​Missing overrides

​Troubleshooting

​Override not applied

​Lockfile out of sync

​Check what was overridden

​Best practices

​Document overrides

​Be specific

​Test thoroughly

​Review periodically

​Use with caution

​Advanced patterns

​Conditional overrides

​Multiple package versions

​Override transitive peer dependencies

​Related features

​Catalogs

​Patches

​Resolutions

Build docs developers (and LLMs) love

What are overrides?

Configuration

In package.json

Nested overrides

Deep nested overrides

Use cases

Security patches

Fix bugs

Force specific versions

Replace unmaintained packages

Syntax

Exact version

Version range

Package alias

All versions

Reference parent version

Scoped overrides

Override for specific parent

Multiple levels

Wildcard parent

Examples

Security fix

Deduplicate React versions

Fix peer dependency conflicts

Replace deprecated package

Comparison with resolutions

Yarn resolutions

npm overrides

pnpm overrides

Verification

Check overrides are applied

View dependency tree

Warnings

Version conflicts

Missing overrides

Troubleshooting

Override not applied

Lockfile out of sync

Check what was overridden

Best practices

Document overrides

Be specific

Test thoroughly

Review periodically

Use with caution

Advanced patterns

Conditional overrides

Multiple package versions

Override transitive peer dependencies

Related features

Catalogs

Patches

Resolutions