npm install fails with 'sh: node-gyp-build: command not found'
sh: node-gyp-build: command not foundShort 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.
Fix it fast
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"2Match what you see, then jump to its fix
What does the error look like?
sh: node-gyp-build: command not foundnpm 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 omit2Fix
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=dev3Verify
Run the same install again.
npm installConfirmed by docs.npmjs.com
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 | head2Fix
Remove node_modules and install again, so npm creates the links.
rm -rf node_modules
npm install3Verify
The executable now exists and the install passes.
ls node_modules/.bin | grep node-gyp-buildConfirmed by docs.npmjs.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
Node reports that no native build was found for your platform
loaded from: <path to the package>
The package loads its native .node file through node-gyp-build.
4 causes, each with a fixWeb apps
Playwright cannot open a headed browser on a Linux server or in Docker
npx playwright test --headed shows no window on a Linux server
A headed browser needs a display, and a Linux server or container has none.
3 causes, each with a fixWeb apps
React dev server in Docker does not reload when you save a file
Changes appear only after docker compose restart or a rebuild
File-change events often do not cross from your host into a container, so the dev server never notices the edit.
3 causes, each with a fixWeb apps
T3 Env stops the build with Invalid environment variables
Error: Invalid environment variables
T3 Env validates process.env against your Zod schema when the app starts or builds, and stops on the first failure.
4 causes, each with a fixWeb apps
vite build cannot find index.html, especially inside Docker
Could not resolve entry module (index.html)
Vite treats index.html as the entry of the app and looks for it in the project root, which is the folder where you run the command.
4 causes, each with a fixWeb apps
Vite environment variables are undefined inside a Docker container
VITE_ variable shows undefined in the browser console
Vite replaces import.meta.env values while it builds, not when the container starts.
3 causes, each with a fix