pnpm ERR_PNPM_IGNORED_BUILDS: Migrate to allowBuilds

What the error means#

pnpm can install a package without running its postinstall, install, or other lifecycle build script. That protects an install from automatically executing dependency code, but packages with native binaries or generated artifacts may not work until their scripts are explicitly allowed.

In pnpm v11, strictDepBuilds defaults to true. An unreviewed build script can therefore turn what used to be a warning into a failed install. The pnpm 11 release notes document both the stricter default and the replacement of the old build-dependency settings with allowBuilds.

The error is about a package’s install script, not necessarily about the package being unavailable:

1
ERR_PNPM_IGNORED_BUILDS
2
Ignored build scripts: esbuild, sharp
3
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

The package names in a real log are the starting point for the review. Do not copy this example into your configuration without checking your own dependency tree.

Inspect the blocked packages first#

Run the diagnostic command from the workspace root:

1
pnpm ignored-builds

If the command lists a package, inspect why your application needs its build output. Native modules, image processors, browser binaries, and packages that compile optional code are common reasons, but the package name alone is not proof that its script is safe or required.

Check the package’s scripts and the dependency that brought it into the tree:

1
pnpm why esbuild
2
pnpm view esbuild scripts --json

Use the exact package and version from your lockfile when reviewing a CI failure. A transitive dependency can change its install behavior in a new release, so record the lockfile change together with the approval decision.

Put approvals in pnpm-workspace.yaml#

The v11 configuration is a map from package name patterns to booleans. true allows the package’s build script to run; false records that the package is intentionally denied:

1
allowBuilds:
2
  esbuild: true
3
  sharp: true
4
  fsevents: false

Keep only the packages that you reviewed. The false entries are useful when a package is expected to be present but must not execute an install script. The pnpm settings reference documents this setting alongside strictDepBuilds.

You can let pnpm update the map interactively:

1
pnpm approve-builds

Or name the decisions explicitly in a repeatable command:

1
pnpm approve-builds esbuild sharp !fsevents

The current approve-builds documentation supports positional package names and uses ! to deny a package. Review the resulting YAML diff before committing it.

Migrate a pnpm v10 project#

An older project may still have configuration like this in package.json:

1
{
2
  "pnpm": {
3
    "onlyBuiltDependencies": ["esbuild"],
4
    "ignoredBuiltDependencies": ["fsevents"]
5
  }
6
}

pnpm v11 no longer reads the pnpm field in package.json for these settings. Move the decisions to pnpm-workspace.yaml:

1
allowBuilds:
2
  esbuild: true
3
  fsevents: false

The official v10-to-v11 migration guide includes a codemod that consolidates the old build-dependency settings into allowBuilds. Run it in a branch, inspect every generated entry, and test the install on the same Node.js version used by CI.

Do not keep two competing sources of truth and assume pnpm will merge them. A configuration that works with one pnpm major can be silently ignored by another.

Make CI use the same decision#

Commit pnpm-workspace.yaml and run a clean, frozen install in CI:

1
rm -rf node_modules
2
pnpm install --frozen-lockfile
3
pnpm run build

The rm -rf node_modules line is useful for a local migration check; in CI, use the runner’s clean workspace or explicitly invalidate a cache when you need to prove that no old build artifacts are masking the result. Keep the lockfile and the pnpm version pinned so local and CI installs evaluate the same dependency graph.

If a package is allowed but its build still fails, that is a second problem. Check the Node.js version, platform-specific optional dependencies, compiler toolchain, and the package’s own installation instructions. Changing strictDepBuilds will not fix a broken native compilation.

Setting strictDepBuilds: false can be a temporary compatibility bridge while migrating, but it hides the review signal and should not replace an allowlist:

1
strictDepBuilds: false
2
allowBuilds:
3
  esbuild: true

Prefer an explicit allowBuilds map for production and CI. Avoid a global allow-all setting unless you have a separate supply-chain review process for every install script.

Verify the result at the install boundary#

After editing the configuration, verify the same path that failed:

1. Run pnpm ignored-builds and confirm the remaining packages are intentional.
2. Remove stale node_modules or use a clean CI runner.
3. Run pnpm install --frozen-lockfile.
4. Run the build or test command that needs the generated artifact.
5. Review the lockfile and pnpm-workspace.yaml as one change.

If pnpm ignored-builds is empty but the application still cannot load a native module, inspect the package’s runtime error instead of adding more approvals. If the install still reports a package that is already in allowBuilds, check whether the configuration is in the workspace root and whether the CI job is actually using pnpm v11.

The practical rule is to treat ERR_PNPM_IGNORED_BUILDS as a dependency trust decision. Approve the smallest reviewed set, keep it in the workspace configuration, and make CI reproduce that decision from a clean install.

The existing ERR_PNPM_WORKSPACE_PKG_NOT_FOUND guide covers a different pnpm boundary: package discovery and workspace globs. Do not use a workspace glob change to solve an ignored build script.

FAQ#