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

# 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

```json theme={null}
{
  "overrides": {
    "lodash": "4.17.21"
  }
}
```

This replaces **all** occurrences of `lodash` with version `4.17.21`.

### Nested overrides

Override dependencies of specific packages:

```json theme={null}
{
  "overrides": {
    "foo": {
      "bar": "1.0.0"
    }
  }
}
```

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

### Deep nested overrides

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "overrides": {
    "node-fetch": "2.6.7"
  }
}
```

### Force specific versions

Ensure consistent versions across dependencies:

```json theme={null}
{
  "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

```json theme={null}
{
  "overrides": {
    "old-package": "npm:new-package@^2.0.0"
  }
}
```

## Syntax

### Exact version

```json theme={null}
{
  "overrides": {
    "lodash": "4.17.21"
  }
}
```

### Version range

```json theme={null}
{
  "overrides": {
    "lodash": "^4.17.0"
  }
}
```

### Package alias

```json theme={null}
{
  "overrides": {
    "old-lib": "npm:new-lib@^1.0.0"
  }
}
```

### All versions

```json theme={null}
{
  "overrides": {
    "lodash": "*"
  }
}
```

Uses latest version.

### Reference parent version

```json theme={null}
{
  "dependencies": {
    "react": "^18.2.0"
  },
  "overrides": {
    "react": "$react"
  }
}
```

Uses the version specified in `dependencies`.

## Scoped overrides

### Override for specific parent

```json theme={null}
{
  "overrides": {
    "package-a": {
      "lodash": "4.17.21"
    }
  }
}
```

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

### Multiple levels

```json theme={null}
{
  "overrides": {
    "package-a": {
      "package-b": {
        "lodash": "4.17.21"
      }
    }
  }
}
```

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

### Wildcard parent

```json theme={null}
{
  "overrides": {
    "*": {
      "lodash": "4.17.21"
    }
  }
}
```

Same as global override.

## Examples

### Security fix

```json theme={null}
{
  "name": "my-app",
  "dependencies": {
    "express": "^4.17.0"
  },
  "overrides": {
    "qs": "6.11.0"
  }
}
```

Install:

```bash theme={null}
$ bun install

Warning: Overriding qs@6.9.0 with 6.11.0

+ 57 packages installed [892ms]
```

### Deduplicate React versions

```json theme={null}
{
  "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

```json theme={null}
{
  "dependencies": {
    "library-a": "^1.0.0",
    "library-b": "^2.0.0"
  },
  "overrides": {
    "library-a": {
      "peer-dep": "^2.0.0"
    }
  }
}
```

### Replace deprecated package

```json theme={null}
{
  "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:

```json theme={null}
{
  "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+:

```json theme={null}
{
  "overrides": {
    "lodash": "4.17.21"
  }
}
```

### pnpm overrides

pnpm uses `pnpm.overrides`:

```json theme={null}
{
  "pnpm": {
    "overrides": {
      "lodash": "4.17.21"
    }
  }
}
```

Bun reads `pnpm.overrides` when migrating from pnpm.

## Verification

### Check overrides are applied

After installing:

```bash theme={null}
$ 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

```bash theme={null}
bun pm ls --all
```

Verify all instances use the override version.

## Warnings

### Version conflicts

Bun warns about overrides that might break compatibility:

```bash theme={null}
$ 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:

```bash theme={null}
$ 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

```bash theme={null}
# Verify package exists
bun pm view lodash@4.17.21
```

### Lockfile out of sync

After adding overrides:

```bash theme={null}
rm bun.lockb
bun install
```

### Check what was overridden

```bash theme={null}
bun pm ls | grep "(overridden"
```

## Best practices

### Document overrides

Add comments explaining why:

```json theme={null}
{
  "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:

```json theme={null}
{
  "overrides": {
    // Only override for package-a
    "package-a": {
      "lodash": "4.17.21"
    }
  }
}
```

### Test thoroughly

Overrides can break functionality:

```bash theme={null}
bun install
bun test
```

### Review periodically

Remove overrides when upstream packages update:

```bash theme={null}
# 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:

```json theme={null}
// package.json (development)
{
  "overrides": {
    "debug": "^4.0.0"
  }
}

// package.production.json
{
  "overrides": {
    "debug": "^3.0.0"
  }
}
```

### Multiple package versions

```json theme={null}
{
  "overrides": {
    "package-v1": "npm:package@^1.0.0",
    "package-v2": "npm:package@^2.0.0"
  }
}
```

### Override transitive peer dependencies

```json theme={null}
{
  "overrides": {
    "*": {
      "@types/react": "18.0.0"
    }
  }
}
```

## Related features

### Catalogs

For managing shared versions across workspaces, see [catalogs](/install/catalogs).

### Patches

For patching package code, see `bun patch` command.

### Resolutions

Bun supports Yarn's `resolutions` field for compatibility:

```json theme={null}
{
  "resolutions": {
    "lodash": "4.17.21"
  }
}
```