Maaz Zindani

Loading the index…

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

npm install fails inside a node:alpine Docker build

Errorgyp ERR! find Python

Short answer

The node alpine images ship almost nothing beyond Node.js, so a native module that node-gyp must compile has no Python, make or C++ compiler. Install build-base and python3 with apk before npm install, preferably in a build stage. If a prebuilt binary fails at runtime instead, the cause is musl versus glibc.

  • Applies to node:22-alpine, node-gyp 10, npm 10
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the first gyp ERR! line in the failed build output. A message about Python, make or a compiler means the toolchain is absent. If the install passes and only the running app fails, suspect a glibc binary on musl.

    docker build --progress=plain --no-cache -t my-app . 2>&1 | grep -m5 "gyp ERR"
  2. 2Match what you see, then jump to its fix

    1. 1gyp ERR! find Python, or make / g++ not found during npm installThe alpine image has no compiler toolchain or PythonFix
    2. 2The install passes but the app crashes at start, on a package that ships a prebuilt binaryA prebuilt binary was made for glibc, but Alpine uses muslFix

What does the error look like?

  • gyp ERR! find Python
  • Docker Node Alpine Image Build Fails on node-gyp

Cause 1 of 2

The alpine image has no compiler toolchain or Python

1Check

node-gyp needs Python, make and a C/C++ toolchain such as GCC on Unix. The node alpine images are minimal; their README says even git and bash are not included.

docker run --rm node:22-alpine sh -c "which python3 make g++ || echo missing"

2Fix

Add the Alpine packages before npm install. build-base is a meta package that pulls in gcc, g++, make and the C library headers.

FROM node:22-alpine
RUN apk add --no-cache python3 build-base
WORKDIR /app
COPY package*.json ./
RUN npm ci

3Verify

Rebuild the image; npm ci now finishes the native module step.

docker build -t my-app .

Confirmed by github.com

Did this fix it?

Cause 2 of 2

A prebuilt binary was made for glibc, but Alpine uses musl

1Check

The Docker Node README states Alpine uses musl libc, not the glibc of Debian, and that software written for Debian will generally not run under Alpine.

docker run --rm node:22-alpine sh -c "ldd --version 2>&1 | head -n 2"

2Fix

Prefer a package version that supports musl or compiles from source (with the tools from the first cause). The README names gcompat as a compatibility layer that may help; or switch the base image to a Debian-based tag such as node:22-slim.

RUN apk add --no-cache gcompat

3Verify

Run the container and start the app.

docker run --rm my-app node -e "console.log('ok')"

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Install build tools in a separate build stage, and copy only node_modules and your code into the final image.
  • Copy package*.json first and run npm ci, so the layer is cached until dependencies change.
  • If native modules are many, consider the Debian-based slim image instead of fighting musl.

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

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.