Node "Cannot find module 'node-gyp'" - Fix Missing node-gyp on Native Install in CI

By Kaveh Alemi·Latchkey

A native dependency tried to compile and could not find node-gyp - the tool that drives the build. Modern npm bundles node-gyp, so this usually means a very old/odd npm, a stripped install, or a broken global setup.

What this error means

Installing a package with a native addon fails because node-gyp itself is missing - Cannot find module 'node-gyp' or gyp ERR! node-gyp not found. The compile never starts because the build tool is absent.

npm output

npm error gyp ERR! configure error
npm error gyp ERR! stack Error: Cannot find module 'node-gyp'
npm error gyp ERR! stack     at Function._resolveFilename (node:internal/modules/cjs/loader)

Common causes

node-gyp not available to the install

A very old npm, a global setup missing node-gyp, or an environment that stripped it leaves native builds with no build driver.

Toolchain present but node-gyp not resolvable

Even with a compiler installed, if node-gyp cannot be resolved (broken global modules, custom prefix), the native build cannot proceed.

How to fix it

Provide node-gyp and the toolchain

Update npm (which bundles node-gyp) or install node-gyp explicitly, plus the build tools.

Terminal

npm install -g npm@latest        # bundles a current node-gyp
# or install node-gyp explicitly
npm install -g node-gyp
# and the toolchain it drives
apt-get update && apt-get install -y python3 make g++
npm ci

Fix the resolution path

Use a CI image where npm bundles node-gyp and the toolchain is present.
Check a custom npm prefix is not hiding node-gyp from resolution.
Prefer packages with prebuilt binaries to avoid building at all.

How to prevent it

Use a current npm so node-gyp is bundled.
Bake Python + a C/C++ toolchain into CI images with native deps.
Prefer prebuilt-binary packages where possible.

Frequently asked questions

What causes ""Cannot find module 'node-gyp'""?