Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

pnpm: Ignored build scripts and how to approve them

A skipped postinstall leaves native modules empty. Approve the packages once in committed config, then verify the build instead of allowing everything.

~5 min readNode.js
#pnpm#Node.js#Package Managers#Security
A package crate with an empty socket where a native binary should snap in, an amber approval key above it

Introduction & Quick Summary

Symptom. pnpm install finishes with a green lockfile and a warning block instead of a build failure, and the failure arrives later as a missing binary:

code
╭ Warning ──────────────────────────────────────────╮ │ Ignored build scripts: esbuild, sharp. │ │ Run "pnpm approve-builds" to pick which │ │ dependencies should be allowed to run scripts. │ ╰─────────────────────────────────────────────────╯

Then next build dies with Error: Could not load the "sharp" module using the linux-x64 runtime, or Vitest throws Cannot find module '@esbuild/linux-x64', or a Prisma client reports that its engines were never downloaded. It works on a colleague's machine, whose node_modules predates the upgrade.

Cause. Since pnpm 10, dependency lifecycle scripts (preinstall, install, postinstall) are not executed unless the package is explicitly allowed. The default flipped from "run everything" to "run nothing you did not approve" as a supply-chain measure. Native packages that compile or download a platform binary in postinstall therefore install as empty shells.

Fix. Approve the specific packages, in a file that is committed, so CI and every developer gets the same decision:

bash
# current pnpm: records allowBuilds: true entries in pnpm-workspace.yaml pnpm approve-builds esbuild sharp # or approve everything still pending, non-interactively (CI bootstrap only) pnpm approve-builds --all pnpm install
# pnpm-workspace.yaml, committed onlyBuiltDependencies: - esbuild - sharp

The rest of this guide covers which form your pnpm version reads, why package.json is no longer the reliable place for the setting, and how to keep the decision narrow instead of reaching for dangerouslyAllowAllBuilds.

Core Mechanics, Signatures & Reproducible Setup

pnpm resolves the node_modules tree from the lockfile without running any dependency code, then, in a separate phase, runs lifecycle scripts for the packages the policy allows. The policy lives in project configuration, and the file it reads has moved during the 10.x line.

Reproduce the failure in an empty directory, with no project of your own involved:

bash
mkdir /tmp/pnpm-demo && cd /tmp/pnpm-demo pnpm init pnpm add esbuild@0.25.1 ls node_modules/.pnpm/esbuild@0.25.1/node_modules/esbuild/bin/ # empty or missing node -e "require('esbuild').transformSync('let a: number = 1')"

The last command throws because the platform package that ships the actual binary never had its install step run. With the allowance in place, the same install prints no warning and the binary appears.

Four settings decide what runs, and they are not interchangeable:

# pnpm-workspace.yaml (authoritative in current pnpm) onlyBuiltDependencies: # allow-list; everything else is blocked - esbuild - sharp@0.34.1 # version-scoped allowances are supported ignoredBuiltDependencies: # known-safe to skip; no warning, no prompt - fsevents neverBuiltDependencies: # deny-list, but implies everything else is allowed - core-js dangerouslyAllowAllBuilds: true # opt out of the protection entirely

Two details trip people up. neverBuiltDependencies does not mean "block these and block the rest"; it means "block these and allow the rest", which is the pre-10 behaviour. And current pnpm accepts a map form instead of a list, which is what the approval command writes:

# pnpm 10.26 and later allowBuilds: esbuild: true core-js: false

Which file wins is the other half of the confusion. Early 10.x releases documented pnpm.onlyBuiltDependencies inside package.json; later releases moved settings to pnpm-workspace.yaml, and the workspace file overrides a single package's manifest field.

bash
pnpm config get onlyBuiltDependencies pnpm --version

Key Comparison Table

SettingRuns scripts forWarning when a script is skippedTypical use
nothing set (default)no dependencyyes, with the package listsafest baseline
onlyBuiltDependencieslisted packages onlyyes, for unlisted onescommitted allow-list
ignoredBuiltDependenciesunlisted packagesno, silent for the listed oneshiding known noise
neverBuiltDependencieseverything except the listednolegacy behaviour
dangerouslyAllowAllBuildseverythingnonever in a shared repo
strictDepBuilds: truelisted packages onlyinstall fails insteadCI enforcement
PackageWhat the skipped script doesSymptom when it is skipped
esbuilddownloads or links the platform binaryCannot find module '@esbuild/linux-x64'
sharpinstalls libvips bindingsCould not load the "sharp" module
@prisma/enginesdownloads query enginesPrismaClientInitializationError
better-sqlite3compiles with node-gypbindings file not found

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Reading the warning instead of the failure

It prints once per install. On CI the output is collapsed into the failing step, so keep the tail of the log:

bash
pnpm install --reporter=append-only 2>&1 | tee install.log grep -n "Ignored build scripts" install.log

If the project has a frozen lockfile check, a skipped build and a drifted lockfile look the same in a red pipeline. Resolve them in order: --frozen-lockfile first, then the build allowance. ERR_PNPM_OUTDATED_LOCKFILE means the lockfile is the problem, not the scripts.

2. CI cannot answer an interactive prompt

pnpm approve-builds with no arguments is an interactive checklist that writes the answer back to the config file. In a pipeline there is no terminal, and current pnpm exits with ERR_PNPM_APPROVE_BUILDS_NON_INTERACTIVE rather than guessing:

bash
# deterministic: name the packages, keep the diff reviewable pnpm approve-builds esbuild sharp # bootstrap only: accept every pending package in this repo pnpm approve-builds --all # deny a package that keeps asking pnpm approve-builds '!core-js'

An approval written into the config file is a review artefact that changes what runs on every machine, so approve in the same commit that adds the dependency.

3. Docker builds and the store cache

Inside a container the failure is usually a second-order effect of caching: the store layer is restored and node_modules is linked, but the allowance from the previous image is not there.

dockerfile
FROM node:24-alpine AS deps WORKDIR /app RUN corepack enable COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./ RUN pnpm install --frozen-lockfile FROM node:24-alpine AS build WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY . . RUN pnpm run build

Copying pnpm-workspace.yaml into the deps stage is what makes the allowance travel with the image. If the file is missing there, install succeeds with warnings and the build stage fails on the native module, which makes the Dockerfile look innocent.

4. Global installs and the other store

pnpm add -g uses the global package configuration, not the project file, so a CLI installed globally hits the same warning with no project involved. Approve it explicitly with pnpm approve-builds -g, and put that in the bootstrap script rather than in someone's shell history. This matters for tools a script installs, such as a database CLI whose postinstall compiles an addon.

5. Distinguishing a skipped script from a real build bug

Before changing configuration, prove that the script is the problem. A package that builds natively and fails because of a missing toolchain prints compiler output; a package whose script was skipped prints nothing and misses files:

bash
pnpm rebuild sharp # runs only the approved packages pnpm rebuild --pending # runs everything still pending node -e "console.log(require('sharp').versions)"

pnpm rebuild --pending is the shortest test: if the runtime error disappears and no compiler output appears, the allowance was the whole problem. Compiler output instead means a real toolchain issue, and python3, make and g++ are the next suspects.

6. Keeping the decision narrow over time

An allow-list rots in one direction: someone approves everything pending to unblock a build, and the list silently grows. Pin versions where a script is only needed for one major, and enable strict mode in CI so a new unapproved script fails the build instead of printing a warning nobody reads:

# pnpm-workspace.yaml strictDepBuilds: true onlyBuiltDependencies: - esbuild@0.25.1 - sharp
bash
pnpm install --frozen-lockfile # fails on any newly added unapproved script

Review the list like a dependency bump: a package that needs postinstall executes code in your build environment, which is what the default protects against.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Assuming the warning is harmless. It surfaces as a runtime error in a different step, often in production.
  • Setting pnpm.onlyBuiltDependencies in one workspace package. Workspace-level configuration wins.
  • Reaching for dangerouslyAllowAllBuilds to unblock CI. It re-opens the whole graph, including transitive packages added later.
  • Using neverBuiltDependencies as a deny-list. It also allows everything else.
  • Running pnpm approve-builds interactively inside a container. Use names or --all.
  • Forgetting to copy pnpm-workspace.yaml into the Docker deps stage. The allowance never reaches the image.
  • Deleting node_modules to "reset" the state. The policy lives in configuration.
  • Trusting install output on a warm store. Test with pnpm rebuild --pending.

Check the config file you are editing with the JSON formatter when it is a manifest, and keep the YAML honest with the YAML validator before committing a workspace setting. Environment variables that decide which build path runs (NODE_ENV, npm_config_*) are easier to read side by side with the environment file inspector.

Reference: pnpm settings, pnpm approve-builds, and the pnpm 10 release notes that introduced the default.

Official references

primary documentation

The Node.js documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Node.js work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Node.js guides

More in Node.js

All Node.js guides

The guides filed next to this one in Node.js, in library order.