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

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

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 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:

1. Package name - Must match exactly
2. Version exists - Verify version exists in registry
3. Syntax - Validate JSON syntax

# Verify package exists
bun pm view lodash@4.17.21

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

Related features

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