Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm install stops while building a native module with node-gyp

Errorgyp ERR! find Python

Short answer

node-gyp compiles native add-ons, so it needs a supported Python and a C/C++ compiler. The log shows which one is missing. Install the compiler tools for your system, point node-gyp at a supported Python, and use node-gyp 10 or newer if Python is 3.12 or later.

  • Applies to node-gyp 10, Node.js 22, Python 3.12, Ubuntu 24.04, macOS 15, Windows 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Re-run the install with more detail and read the gyp lines above the final error. They list every Python it tried.

    npm install --loglevel=verbose 2>&1 | grep -i gyp
  2. 2Match what you see, then jump to its fix

    1. 1Could not find any Python installation to useNo supported Python can be foundFix
    2. 2Found unsupported Python version, or errors from Python itself, with Python 3.12 or laterPython is too new for an old node-gypFix
    3. 3gyp ERR! build error, with make, gcc, g++ or clang not found; or on Windows, no Visual Studio foundThe C/C++ compiler or build tools are missingFix

What does the error look like?

  • gyp ERR! find Python
  • Could not find any Python installation to use
  • Found unsupported Python version
  • gyp ERR! build error

Cause 1 of 3

No supported Python can be found

1Check

node-gyp tries a Python from the command line, the PYTHON variable, then python3 and python. It accepts 3.6 or newer. On Windows it also tries the py launcher and common install folders.

python3 --version
echo "$PYTHON"

2Fix

Install a current Python, or tell node-gyp which one to use. NODE_GYP_FORCE_PYTHON overrides every other setting.

export npm_config_python=/usr/bin/python3
npm install

3Verify

The install gets past the configure step.

npm install --loglevel=verbose 2>&1 | grep -i python

Confirmed by github.com

Did this fix it?

Cause 2 of 3

Python is too new for an old node-gyp

1Check

If node-gyp is installed globally it reports its version. node-gyp's README says Python 3.12 or later needs node-gyp 10 or newer. A pinned old version of node-gyp breaks on it.

node-gyp --version
python3 --version

2Fix

Install node-gyp 10 or later.

npm install -g node-gyp

3Verify

The node-gyp version is 10 or higher.

node-gyp --version

Confirmed by github.com

Did this fix it?

Cause 3 of 3

The C/C++ compiler or build tools are missing

1Check

On Linux node-gyp needs make and a C/C++ toolchain, on macOS the Xcode Command Line Tools, on Windows Visual Studio with the Desktop development with C++ workload.

make --version
g++ --version
# macOS: xcode-select -p

2Fix

Install the toolchain for your system.

# Ubuntu / Debian
sudo apt install build-essential
# macOS
xcode-select --install

3Verify

Run the install again; compilation proceeds.

npm install

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Prefer packages that ship prebuilt binaries, and keep Node.js on an LTS line they support.
  • Keep npm and node-gyp current so they match your Python.
  • Document the build tools your project needs in its README or CI image.

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.