Skip to content
Bun
oven-sh/bun96,440
Bun
Advanced Configuration

bun patch

Persistently patch node_modules packages in a git-friendly way

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
  • .patch files can be committed to your repository and reused across installs, projects, and machines
  • "patchedDependencies" in package.json keeps track of patched packages
  • 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, patched packages are committed to the Global Cache and shared 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 [email protected]

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

Don’t skip bun patch <pkg>. 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.

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/ and diffing it 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 [email protected]

# 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

CLI Usage

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 in the project’s package.json (dependency scripts are never run)

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

--backendstringdefault: clonefile

Platform-specific optimizations for installing dependencies. Possible values: clonefile (default), hardlink, symlink, copyfile

--linkerstring

Linker strategy (one of isolated or hoisted)

--dry-runboolean

Don’t install anything

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

--registrystring

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

--network-concurrencynumberdefault: 48

Maximum number of concurrent network requests (default 48)

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

Only show tarball name when packing

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

Global Configuration & Context

--configstring

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

--cwdstring

Set a specific current working directory

Help

--helpboolean

Print this help menu. Alias: -h

On this page

Step 1. Prepare the package for patchingStep 2. Test your changes locallyStep 3. Commit your changesPatch GenerationDependency ManagementProject Files & LockfilesInstallation ControlNetwork & RegistryPerformance & ResourceCachingOutput & LoggingPlatform TargetingGlobal Configuration & ContextHelp