NPM-PATCH(1)

NAME
npm-patch - Apply local patches to installed dependencies

  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.

  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

  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.

SEE ALSO

    •   npm help install

    •   npm help ci

    •   package-lock.json ⟨/configuring-npm/package-lock-json⟩

    •   npm help config