NPM-PATCH(1) NPM-PATCH(1)

# [NAME](#NAME)

**npm-patch** - Apply local patches to installed dependencies

## [Synopsis](#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](#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 &lt;pkg&gt;** is shorthand for **npm patch add &lt;pkg&gt;**. A package literally named like a subcommand must use the explicit form, e.g. **npm patch add add**.

•

**npm patch add &lt;pkg&gt;\[@&lt;version&gt;]**

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 **&lt;pkg&gt;** is installed, re-run with an exact selector such as **npm patch add lodash@4.17.21**.

•

**npm patch commit &lt;edit-dir&gt;**

Diffs the edited directory against a clean copy of the original tarball, writes the unified diff to **&lt;patches-dir&gt;/&lt;name&gt;@&lt;version&gt;.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 &lt;pkg&gt;\[@&lt;version&gt;]**

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

## [Failure modes](#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](#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](#SEE_ALSO)

- npm help install
- npm help ci
- **package-lock.json** *⟨/configuring-npm/package-lock-json⟩*
- npm help config

October 2026 NPM@12.2.1

---

Document: npm-patch(1) from npm-12 12.2.1-r1 (Chainguard OS)
Source: https://github.com/npm/cli