Scroll to navigation

NPM-PATCH(1) General Commands Manual NPM-PATCH(1)

NAME

npm-patch

Synopsis

<!-- AUTOGENERATED USAGE DESCRIPTIONS -->.SH Description

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

<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->

See Also

  • npm install
  • npm ci
  • package-lock.json
  • config

September 2026 12.0.2