node-gyp "find Python" failed in CI

node-gyp compiles native addons and requires a Python interpreter for its build scripts. The install failed because no usable Python was found on the runner.

What this error means

A package with a native addon fails to install with "gyp ERR! find Python" and "Could not find any Python installation to use". It builds locally because your machine has Python.

node

gyp ERR! find Python
gyp ERR! find Python Python is not set from command line or npm configuration
gyp ERR! find Python You need to install the latest version of Python.

Common causes

No Python on the runner

A minimal image ships without Python, so node-gyp cannot run its build scripts.

Python present but not discoverable

Python exists under an unexpected name/path and is not on PATH or set via npm config.

How to fix it

Install Python before the native build

Add a Python setup step so node-gyp can find an interpreter.

workflow

# workflow
- uses: actions/setup-python@v5
  with: { python-version: '3.12' }
- run: npm ci

Point node-gyp at the interpreter

If Python is installed under a custom path, tell node-gyp explicitly.

Terminal

npm config set python /usr/bin/python3
# or per-invocation
npm_config_python=/usr/bin/python3 npm ci

How to prevent it

Provision Python on runners that build native addons.
Set npm config python when the interpreter is in a non-standard path.
Prefer prebuilt binaries to avoid the native toolchain entirely.