---
title: "bun patch"
description: "Persistently patch node_modules packages in a git-friendly way"
---

import Patch from "/snippets/cli/patch.mdx";

`bun patch` persistently patches packages in `node_modules` in a maintainable, git-friendly way.

Sometimes you need a small change to a package in `node_modules/` to fix a bug or add a feature. `bun patch` lets you do this without vendoring the entire package.

Features:

- Generates `.patch` files that Bun applies to dependencies in `node_modules` on install
- You can commit `.patch` files to your repository and reuse them across installs, projects, and machines
- `"patchedDependencies"` in `package.json` keeps track of patched packages. Bun only reads it from the root `package.json`; `bun install` warns when a workspace package declares it.
- Patches packages in `node_modules/` while preserving the integrity of Bun's [Global Cache](/pm/global-cache)
- Test your changes locally before committing them with `bun patch --commit <pkg>`
- To preserve disk space and keep `bun install` fast, Bun commits patched packages to the Global Cache and shares them across projects where possible

#### Step 1. Prepare the package for patching

Use `bun patch <pkg>` to prepare the package for patching:

```bash terminal icon="terminal"
# you can supply the package name
bun patch react

# ...and a precise version in case multiple versions are installed
bun patch react@17.0.2

# or the path to the package
bun patch node_modules/react
```

<Note>
Always run `bun patch <pkg>` first. It ensures the package folder in `node_modules/` contains a fresh copy of the package with no symlinks or hardlinks to Bun's cache.

If you skip it, you might end up editing the package globally in the cache.

</Note>

#### Step 2. Test your changes locally

`bun patch <pkg>` makes it safe to edit `<pkg>` in `node_modules/` directly, while preserving the integrity of Bun's [Global Cache](/pm/global-cache). It works by re-creating an unlinked clone of the package in `node_modules/`. `bun patch --commit <pkg>` then diffs that clone against the original package in the Global Cache.

#### Step 3. Commit your changes

Once you're happy with your changes, run `bun patch --commit <path or pkg>`.

Bun generates a patch file in `patches/`, updates your `package.json` and lockfile, and starts using the patched package:

```bash terminal icon="terminal"
# you can supply the path to the patched package
bun patch --commit node_modules/react

# ... or the package name and optionally the version
bun patch --commit react@17.0.2

# choose the directory to store the patch files
bun patch --commit react --patches-dir=mypatches

# `patch-commit` is available for compatibility with pnpm
bun patch-commit react
```

If `bun install` could not apply the resulting patch, or the install is refused (for example by a [security scanner](/pm/security-scanner-api)), the commit fails and changes nothing: your edits, `package.json`, the lockfile, and any earlier patch file stay as they were.

To run the same checks without writing anything, pass `--dry-run`. It prints the path of the patch file that the commit would write.

#### Removing a patch

Undo your changes and commit again:

```bash terminal icon="terminal"
bun patch react
# restore the files you changed in node_modules/react
bun patch --commit react
```

When the package has no changes left, Bun removes it from `"patchedDependencies"` in `package.json` and the lockfile, deletes its patch file unless another entry uses it, and reinstalls the original package.

You can also delete the entry from `"patchedDependencies"` and the patch file yourself, then run `bun install`.

#### A missing patch file

`bun install` and `bun patch <pkg>` fail when a file in `"patchedDependencies"` does not exist, and leave `node_modules` alone. While the patched package is still in `node_modules`, `bun patch --commit <pkg>` writes the file again. To start over, delete the entry from `"patchedDependencies"` and run `bun install`.

---

<Patch />