Node native addon "node-gyp rebuild" Fails at Runtime in CI - Fix the Build

By Kaveh Alemi·Latchkey

When a native addon has no prebuilt binary for the runner, node-gyp compiles it from source. Missing compilers or Python on the runner make that rebuild fail.

What this error means

A step that loads or rebuilds a native addon fails with node-gyp errors about a missing compiler, missing Python, or an ABI mismatch, aborting the job.

gyp ERR! find Python
gyp ERR! configure error
gyp ERR! stack Error: Could not find any Python installation to use
gyp ERR! System Linux 6.2.0
npm ERR! code 1
npm ERR! command failed: node-gyp rebuild

Common causes

The runner lacks a C/C++ toolchain or Python

node-gyp needs make, a compiler, and Python; a minimal runner image may not have them.

No prebuilt binary for this Node ABI

The addon ships prebuilds for some Node versions but not the one on the runner, forcing a from-source rebuild.

How to fix it

Install the build toolchain

1. Install build-essential and Python on the runner before the addon build.
2. Re-run so node-gyp can compile.

- run: sudo apt-get update && sudo apt-get install -y build-essential python3

Pin a Node version with a matching prebuild

1. Choose a Node version the addon ships a prebuilt binary for.
2. Re-run so no from-source build is needed.

How to prevent it

• Use runner images that include the build toolchain, pin Node to a version with available prebuilds, and cache compiled addons keyed on the Node ABI.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation