npm-patch

Apply local patches to installed dependencies

Select CLI Version:

Table of contents

Synopsis

npm patch <pkg>[@<version>]
npm patch add <pkg>[@<version>] [--edit-dir <path>] [--ignore-existing]
npm patch commit <edit-dir> [--patches-dir <dir>] [--keep-edit-dir]
npm patch update <pkg>[@<old-version>] [--to <new-version>] [--patches-dir <dir>]
npm patch ls
npm patch rm <pkg>[@<version>]

Note: This command is unaware of workspaces.

npm patch lets you apply small, local modifications to an installed dependency and have them re-applied automatically on every install. Patches are declared in the patchedDependencies field of your root package.json, stored as plain unified diffs under the patches/ directory, and recorded with a content hash in package-lock.json.

Because patches are applied during the install itself, they work regardless of install-strategy, apply to transitive dependencies, and are not disabled by --ignore-scripts.

The bare form npm patch <pkg> is shorthand for npm patch add <pkg>. A package literally named like a subcommand must use the explicit form, e.g. npm patch add add.

npm patch add <pkg>[@<version>]

Prepares a package for editing. npm extracts a clean copy of the resolved package tarball into a temporary directory outside node_modules and prints its path. Edit the files there, then run npm patch commit.

If more than one version of <pkg> is installed, re-run with an exact selector such as npm patch add lodash@4.17.21.
npm patch commit <edit-dir>

Diffs the edited directory against a clean copy of the original tarball, writes the unified diff to <patches-dir>/<name>@<version>.patch, adds the entry to patchedDependencies, and updates package-lock.json.
npm patch ls

Lists registered patches and how many installed nodes each one matches.
npm patch rm <pkg>[@<version>]

Removes the matching entries from patchedDependencies, deletes the patch file when no other entry references it, and updates package-lock.json. If <version> is omitted, all entries for <pkg> are removed.

Failure modes

By default any patch problem is a hard error that aborts the install: a patch that fails to apply, a registered patch that matches no installed package, a missing patch file, or a patch whose hash does not match the lockfile.

Two CLI-only flags relax this for one-off cases: --allow-unused-patches and --ignore-patch-failures.

Configuration

`patches-dir`

Default: "patches"
Type: String

The directory, relative to the project root, where npm patch commit writes patch files for patchedDependencies.

`allow-unused-patches`

Default: false
Type: Boolean

Install even when a registered patch in patchedDependencies matches no installed package. Does not silence patch apply failures.

This flag is only honored when passed on the command line; it is ignored in .npmrc and environment variables, and rejected by npm ci.

`ignore-patch-failures`

Default: false
Type: Boolean

Install even when a registered patch fails to apply, with a warning per failure. Intended for incident response only.

This flag is only honored when passed on the command line; it is ignored in .npmrc and environment variables, and rejected by npm ci.

`edit-dir`

Default: null
Type: null or Path

Override the temporary directory used by npm patch add to prepare a package for editing.

`ignore-existing`

Default: false
Type: Boolean

With npm patch add, discard a previous unfinished edit directory and start fresh.

`keep-edit-dir`

Default: false
Type: Boolean

With npm patch commit, do not remove the edit directory after committing the patch.

`to`

Default: null
Type: null or String

Used by npm patch update to set the version to rebase a patch onto when it cannot be read from package-lock.json — for example an exact-version selector, or a version that has not been installed yet.

`registry`

Default: "https://registry.npmjs.org/"
Type: URL

The base URL of the npm registry.