npm install fails inside a node:alpine Docker build
gyp ERR! find PythonShort 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.
Fix it fast
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"2Match what you see, then jump to its fix
What does the error look like?
gyp ERR! find PythonDocker 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 ci3Verify
Rebuild the image; npm ci now finishes the native module step.
docker build -t my-app .Confirmed by github.com
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 gcompat3Verify
Run the container and start the app.
docker run --rm my-app node -e "console.log('ok')"Confirmed by github.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Back end
npm install stops while building a native module with node-gyp
Could not find any Python installation to use
node-gyp compiles native add-ons, so it needs a supported Python and a C/C++ compiler.
3 causes, each with a fixBack end
Airflow SSHOperator stops a long script with SSH command timed out
airflow.exceptions.AirflowException: SSH command timed out
SSHOperator waits only 10 seconds for a command by default.
3 causes, each with a fixBack end
Python asyncio: Task was destroyed but it is pending
RuntimeWarning: coroutine '...' was never awaited
A task was still unfinished when Python threw it away.
4 causes, each with a fixBack end
Celery in a Django project does not connect to Redis or ignores the broker URL
kombu.exceptions.InconsistencyError: ... _kombu.binding.celery
Celery talks to Redis through a client library and reads its broker URL from your Django settings.
4 causes, each with a fixBack 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 fixBack end
Django form POST returns 403 Forbidden: CSRF verification failed
CSRF verification failed. Request aborted.
Django rejects an unsafe request when the CSRF cookie or the form token is missing or wrong, or when the Origin or Referer check fails.
5 causes, each with a fix