Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

npm install fails with 'sh: node-gyp-build: command not found'

Errorsh: node-gyp-build: command not found

Short answer

A package's install script calls node-gyp-build by name. npm only puts executables from installed dependencies on the script PATH, so the error means node-gyp-build is not in node_modules/.bin when the script runs. Install dependencies first, and make sure it is not skipped as a dev dependency.

  • Applies to npm 10, Node.js 22, Docker node:22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the executable exists next to the package that is failing. If it is missing, read the NODE_ENV and omit settings.

    ls node_modules/.bin | grep node-gyp-build
    npm config get omit; echo "$NODE_ENV"
  2. 2Match what you see, then jump to its fix

    1. 1Fails only in production installs, CI images or Docker buildsThe dependency was omitted because it is listed under devDependenciesFix
    2. 2The first install in a fresh folder or after deleting node_modulesThe scripts run before the executable has been linkedFix

What does the error look like?

  • sh: node-gyp-build: command not found
  • npm error command failed

Cause 1 of 2

The dependency was omitted because it is listed under devDependencies

1Check

With NODE_ENV=production npm omits devDependencies by default, and a package whose install script needs node-gyp-build then cannot run it.

echo "$NODE_ENV"; npm config get omit

2Fix

If the failing package is your own, move node-gyp-build into dependencies. If it is a third-party package, install without omitting dev dependencies.

npm install node-gyp-build --save
# or for a one-off install of someone else's package:
npm install --include=dev

3Verify

Run the same install again.

npm install

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 2

The scripts run before the executable has been linked

1Check

npm adds executables of installed dependencies to the PATH of scripts, linked into node_modules/.bin. If node_modules was copied half-way or the install was interrupted, the link does not exist.

ls -la node_modules/.bin | head

2Fix

Remove node_modules and install again, so npm creates the links.

rm -rf node_modules
npm install

3Verify

The executable now exists and the install passes.

ls node_modules/.bin | grep node-gyp-build

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Keep packages that an install script needs in dependencies, not devDependencies.
  • Never copy node_modules between machines or images; run an install there.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.