skip to content

After a project moves to npm 12, `npm ci` succeeds but a native image-resizing addon's binary was never built — why, and what exactly fixes it?

level: seniorimportance: should knowfreq 11%

answer

  1. the install did not fail, it skipped
  2. a default that changed in npm 12
  3. a root package.json field lists approvals
  4. record the approval, then run the script
  5. install-scripts approve, then rebuild

basics

~20 s

Since npm 12, dependency install scripts are skipped unless the root package.json allowScripts field approves them. Run npm install-scripts approve for the addon, npm rebuild it, and commit package.json so npm ci builds it too.

solid answer

~40 s

npm 12.0.0 made dependency install scripts default-deny: `preinstall`, `install` and `postinstall` (and `prepare` for non-registry sources) run only for packages the root `package.json`'s `allowScripts` field approves. A native addon builds in one of those — with a `binding.gyp` and no `install` or `preinstall` of its own, npm's default `install` is `node-gyp rebuild` — so the install skips it, finishes, and only warns that packages "had install scripts blocked because they are not covered by allowScripts". The fix: `npm install-scripts approve @printroom/image-resize`, which writes a pinned entry such as `"@printroom/[email protected]": true`; `npm rebuild @printroom/image-resize` to run the newly approved script now; commit `package.json`. Do not reach for `npm ci --allow-scripts=…`: in a project install that flag is an error (`EALLOWSCRIPTS`). To make CI fail rather than skip, set `strict-allow-scripts`.

code

bash · 12 lines
bash
# npm 12: the install finishes, then warns that scripts were blocked
npm ci
npm install-scripts ls

# record a pinned approval in package.json#allowScripts
npm install-scripts approve @printroom/image-resize

# run the newly approved install script without reinstalling
npm rebuild @printroom/image-resize

# not this: rejected in a project install with EALLOWSCRIPTS
npm ci --allow-scripts=@printroom/image-resize

go deeper

for a junior

Recall that npm 12 skips dependency install scripts until the root package.json approves them, and that the fix is npm install-scripts approve followed by npm rebuild.

for a middle

Explain which events the policy blocks, why a native addon is caught by it, the pinned entry approve writes, and why the install only warns instead of failing.

for a senior

Diagnose the missing binary from the install warning, apply approve then rebuild, reject --allow-scripts on a project install, and add strict-allow-scripts so CI fails on the next unreviewed script.

for a principal

Weigh pinned against name-only approvals: pins force a review on every upgrade, name-only entries trust every future version, and the choice decides how much review load the team carries.

## What changed in npm 12 Up to npm 11, installing a dependency ran its install-time **lifecycle scripts** by default. npm 12.0.0 (July 2026) reversed that: **dependency lifecycle scripts are blocked unless the root package's `allowScripts` policy allows them.** The blocked events are `preinstall`, `install` and `postinstall`, plus `prepare` for packages from non-registry sources such as git. The root project's own scripts are not part of this policy. A native addon is exactly the kind of package this hits. It compiles its binary in an install script, and when a package has a `binding.gyp` file and no `install` or `preinstall` of its own, npm's default `install` script is `node-gyp rebuild`. Under npm 12 that script is skipped until someone approves it. ## Why `npm ci` still "succeeded" The policy does not fail the install by default. npm installs everything, **silently skips** the scripts it was not allowed to run, and ends with a warning such as: `1 package had install scripts blocked because they are not covered by allowScripts:` followed by each package and its scripts. The warning goes to the log on stderr, so a quiet log level hides it. The first visible symptom is often at runtime, when the application cannot load the addon's compiled binary. ## The fix, step by step 1. **See what is waiting for review.** `npm install-scripts ls` lists every installed package whose install scripts are not yet covered by `allowScripts`, without changing anything. 2. **Approve the addon.** `npm install-scripts approve @printroom/image-resize` writes an entry into the root `package.json`. By default the entry is **pinned** to the installed version; `--no-allow-scripts-pin` writes a name-only entry instead. `npm approve-scripts` is an alias. 3. **Run the script now.** `npm rebuild @printroom/image-resize` runs that package's `preinstall`, `install` and `postinstall` (and `prepare` where it applies) without reinstalling the tree. npm's own release note says it in one line: approve, then `npm rebuild` to execute newly approved scripts. 4. **Commit `package.json`.** The next `npm ci`, on a laptop or in CI, finds the approval and runs the build as part of the install. The resulting field looks like this: ```json { "allowScripts": { "@printroom/[email protected]": true, "@printroom/usage-beacon": false } } ``` A `false` entry is a **denial**, written by `npm install-scripts deny`. It is always name-only, and it survives `npm install-scripts approve --all`. ## Flags around the policy | Setting | Where it is valid | Effect | |---|---|---| | `allowScripts` in the root `package.json` | project installs | the team policy, reviewed in pull requests | | `--allow-scripts=<names>` | `npm install -g`, `npm exec`, `npx` | approves packages where no project `package.json` exists; an error (`EALLOWSCRIPTS`) on a project `install`, `ci`, `update` or `rebuild` | | `allow-scripts` in `.npmrc` | any | a name list, used only when no higher layer has a policy | | `strict-allow-scripts=true` | project installs | an unreviewed package fails the install (`ESTRICTALLOWSCRIPTS`) instead of being skipped | | `--dangerously-allow-all-scripts` | any | bypasses the policy entirely; a migration escape hatch, strongly discouraged | | `--ignore-scripts` | any | runs no lifecycle scripts at all and wins over both flags above | The layers do not merge. If the root `package.json` declares `allowScripts`, an `allow-scripts` value in `.npmrc` is ignored with a warning. ## Keeping it working - **Upgrades need re-approval.** A pinned entry matches only that version. When the addon moves to 2.5.0, its scripts are blocked again until you re-run `approve`, which rewrites the pin to the installed version. - **Ranges are not accepted.** Keys must be a bare name or exact versions joined by `||`; a key with `^`, `~` or `>=`, or a dist-tag, is ignored with a warning. - **Stale entries pile up.** `npm install-scripts prune` removes entries that no longer match an installed package with an install script; `--dry-run` previews it. - **The policy lives at the root.** An `allowScripts` field inside a workspace's own `package.json` is ignored, with a warning. - **Make CI loud.** `strict-allow-scripts` turns the silent skip into a failed install, so a new dependency with an install script cannot slip through unreviewed. Why install scripts deserve that review at all is a security question with its own material; the mechanics above are what npm 12 asks of every project that depends on a native addon.

  • How do you allow an install script for a global install or an `npx` run, where there is no project `package.json`?
    Use `--allow-scripts`, for example `npm install -g --allow-scripts=<name>`, or persist it with `npm config set allow-scripts=<name> --location=user`. `npm install-scripts` itself fails with `EGLOBAL` under `-g`, because it has no project `package.json` to write to.
  • How do you make a CI install fail instead of silently skipping an unreviewed install script?
    Set `strict-allow-scripts=true`, for instance in the project `.npmrc`. Any dependency with install scripts that is neither approved nor denied then fails the install with `ESTRICTALLOWSCRIPTS`; explicitly denied packages are still skipped quietly.
  • What does `npm install-scripts prune` remove?
    Entries in `allowScripts`, approvals and denials alike, that no longer match an installed package with an install script — for example a pin left behind after an upgrade, or a package that is gone. It edits only that field, never `.npmrc`, and `--dry-run` shows the changes first.

allowScripts works like the guest list at a venue door: a dependency's install script gets in only if its name, and for a pinned entry its exact version, is on the list. When the addon arrives as 2.5.0, the 2.4.0 entry no longer matches and it waits outside until someone re-approves it.

  • npm 12 still runs a dependency's postinstall on every install by default
  • A blocked install script makes npm ci exit with an error by default
  • Pass --allow-scripts to npm ci to approve the addon in CI
  • Approving the addon is enough; it builds without any further command
  • A caret range in allowScripts keeps approving future minor versions

Assumes npm 12 (anchor 12.2.0): since 12.0.0, dependency install scripts are blocked unless the root allowScripts field approves them; npm 11 and earlier ran them by default.