gyp ERR! build error

# macOS
xcode-select --install

# Debian/Ubuntu
sudo apt install -y build-essential python3

# then, everywhere:
rm -rf node_modules package-lock.json && npm install

What you're seeing

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! stack at ChildProcess.onExit (.../node-gyp/lib/build.js:203:23)
gyp ERR! System Linux 6.5.0
gyp ERR! command "node" ".../node-gyp/bin/node-gyp.js" "rebuild"
gyp ERR! node -v v22.3.0
npm ERR! code 1

Read upward, not at the summary. The gyp ERR! build error line is just the wrapper. The real cause is the first compiler line above it — gcc: command not found, Could not find any Python, or a specific .cpp error.

node-gyp behaves the same on Node.js 18, 20, and 22. But a brand-new Node release (e.g. Node 22 shortly after launch) often has no prebuilt binaries published yet, so more packages fall back to compiling from source — pinning to an LTS Node (Fix 5) sidesteps that.

Fix 1 — Install the C/C++ toolchain (macOS & Linux)

When: errors mention gcc, make, clang, or C++ compiler not found.

# macOS — Command Line Tools bring clang + make
xcode-select --install

# Debian / Ubuntu
sudo apt install -y build-essential python3

# Fedora / RHEL
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y python3

# Alpine (common in Docker)
apk add --no-cache build-base python3

build-essential / the Xcode CLT provide gcc/clang, make, and the headers node-gyp shells out to. This resolves the large majority of Linux and macOS build failures.

Fix 2 — Install the Visual C++ toolchain (Windows)

When: you're on Windows — it has no C++ compiler out of the box.

# easiest: install Visual Studio Build Tools 2022 and select
#   "Desktop development with C++"  (includes MSVC + Windows SDK)
# via winget:
winget install Microsoft.VisualStudio.2022.BuildTools ^
  --override "--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

# plus Python 3 from python.org or the Store, then:
rmdir /s /q node_modules & del package-lock.json & npm install

node-gyp on Windows drives MSVC. Installing the "Desktop development with C++" workload (compiler + Windows SDK) plus Python 3 is what the old windows-build-tools package used to automate.

Fix 3 — Give node-gyp a Python 3 it accepts

When: the log says Could not find any Python installation or picks the wrong one.

python3 --version          # confirm a working Python 3

# point node-gyp explicitly if it can't find it
npm config set python "$(which python3)"
# or per-command
npm install --python=/usr/bin/python3

node-gyp is built on GYP, which runs on Python, so it needs Python 3 on PATH to generate build files. If several Pythons are installed, tell it which one.

Fix 4 — Clean rebuild after a Node upgrade (ABI mismatch)

When: it worked before you changed Node versions.

rm -rf node_modules package-lock.json
npm cache verify
npm install

Native addons are compiled against a specific Node ABI. A Node upgrade invalidates the old build, forcing a rebuild — and if there's no prebuilt binary for the new Node yet, it compiles from source. A clean install (or pinning to LTS, Fix 5) fixes it.

Fix 5 — Skip the compile with a prebuilt binary

When: you'd rather not install a toolchain at all.

# use an LTS Node that the package ships a prebuilt binary for
nvm install --lts && nvm use --lts

# upgrade the offending package to a version with prebuilds
npm install sharp@latest    # example: sharp/better-sqlite3 ship prebuilds

Most popular native packages publish prebuilt binaries for supported Node/OS combinations, so the install just downloads one — no compiler needed. Bleeding-edge Node releases often lack prebuilds, which is why an LTS Node avoids the source build entirely.

Fix 6 — Install the toolchain inside your Docker image

When: it builds locally but fails in docker build — especially on the slim node:alpine image.

# Alpine — node:alpine ships no compiler
RUN apk add --no-cache python3 make g++

# Debian-based (node:22-slim, node:22-bookworm-slim)
RUN apt-get update && apt-get install -y python3 make g++ \
    && rm -rf /var/lib/apt/lists/*

# ...then COPY package*.json and RUN npm install

Slim and Alpine base images strip the build toolchain to stay small, so a package that needs to compile fails with gyp ERR!. Add python3, make, and g++ before npm install. One Alpine gotcha: it uses musl libc, so many packages have no prebuilt binary for it and must compile from source anyway — if you'd rather avoid the toolchain entirely, a node:22-slim (Debian/glibc) base is usually the easier path. For a lean final image, install the toolchain in a builder stage and copy only the result in a multi-stage build.

Common packages that trigger node-gyp

Native compilation is where nearly all gyp errors start. If your install pulls in one of these, it may build an addon:

• Image processing: sharp, canvas
• Databases: better-sqlite3, sqlite3
• Crypto / hashing: bcrypt
• CSS (legacy): node-sass
• FFI & hardware: ffi-napi, usb, serialport

Most of these now publish prebuilt binaries, so an up-to-date version on an LTS Node often skips the compile. Two shortcuts worth knowing: node-sass is deprecated — switching to sass (Dart Sass, pure JavaScript) removes node-gyp from the picture entirely; and bcrypt can be swapped for the pure-JS bcryptjs if you can't get a toolchain.

Why this happens

Some npm packages aren't pure JavaScript — they include C/C++ that must become a platform-specific .node binary. When you install one and no matching prebuilt binary exists, npm runs node-gyp to compile it on your machine. node-gyp is only a coordinator: it needs a real C/C++ compiler (clang/gcc/MSVC), make, and Python 3 (because its GYP core is Python) to do the actual work. If any of those is missing or mismatched, the compile exits non-zero and node-gyp reports gyp ERR! build error. So the fix is never about the package — it's about giving node-gyp the toolchain, or avoiding the compile with a prebuilt.

By platform