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

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

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

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

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.

CLI Usage

bash

bun patch <package>@<version>

Patch Generation

--commitboolean

Install a package containing modifications in dir

--patches-dirstring

The directory to put the patch file in (only if --commit is used)

Dependency Management

--productionboolean

Don't install devDependencies. Alias: -p

--ignore-scriptsboolean

Skip lifecycle scripts for all packages, including the project's package.json and trusted dependencies

--trustboolean

Add to trustedDependencies in the project's package.json and install the package(s)

--globalboolean

Install globally. Alias: -g

--omitstring

Exclude dev, optional, or peer dependencies from install

Project Files & Lockfiles

--yarnboolean

Write a yarn.lock file (yarn v1). Alias: -y

--no-saveboolean

Don't update package.json or save a lockfile

--savebooleandefault true

Save to package.json (true by default)

--frozen-lockfileboolean

Disallow changes to lockfile

--save-text-lockfileboolean

Save a text-based lockfile

--lockfile-onlyboolean

Generate a lockfile without installing dependencies

Installation Control

--backendstring

Platform-specific optimizations for installing dependencies. Possible values: clonefile (default on macOS), hardlink (default on Linux and Windows), symlink, copyfile

--linkerstring

Linker strategy (one of isolated or hoisted)

--minimum-release-agenumber

Only install packages published at least N seconds ago (security feature)

--minimum-release-age-excludesstring

Packages exempt from --minimum-release-age (comma-separated or repeated; replaces the bunfig.toml list)

--dry-runboolean

Print what the command would do, with or without --commit, and leave the project as it is

--forceboolean

Always request the latest versions from the registry & reinstall all dependencies. Alias: -f

--no-verifyboolean

Skip verifying integrity of newly downloaded packages

Network & Registry

--castring

Provide a Certificate Authority signing certificate

--cafilestring

Same as --ca, but as a file path to the certificate

--use-system-caboolean

Use the system's trusted certificate authorities

--use-openssl-caboolean

Use OpenSSL's default CA store instead of the bundled one

--use-bundled-caboolean

Use bundled CA store

--registrystring

Use a specific registry by default, overriding .npmrc, bunfig.toml, and environment variables

--network-concurrencynumberdefault 64

Maximum number of concurrent network requests (default 64)

Performance & Resource

--concurrent-scriptsnumber

Maximum number of concurrent jobs for lifecycle scripts (default: 2x CPU cores)

Caching

--cache-dirstring

Store & load cached data from a specific directory path

--no-cacheboolean

Ignore manifest cache entirely

Output & Logging

--silentboolean

Don't log anything

--quietboolean

Disable the progress bar

--verboseboolean

Excessively verbose logging

--no-progressboolean

Disable the progress bar

--no-summaryboolean

Don't print a summary

Platform Targeting

--cpustring

Override CPU architecture for optional dependencies (e.g., x64, arm64, * for all)

--osstring

Override operating system for optional dependencies (e.g., linux, darwin, * for all)

--libcstring

Override libc for optional dependencies (e.g., glibc, musl, * for all)

Global Configuration & Context

--configstring

Specify path to config file (bunfig.toml). Alias: -c

--cwdstring

Set a specific current working directory

--env-filestring

Load environment variables from the specified file(s)

--no-env-fileboolean

Disable automatic loading of .env files

Help

--helpboolean

Print this help menu. Alias: -h