A Docker build or container says npm: not found
npm: not foundShort answer
A container only has the programs its image holds. npm is in the official node images, not in ubuntu, python, nginx or a bare Alpine image. Check which image and which build stage runs the command. Start from a node image, run npm in the stage that has it, or load nvm in the same RUN.
Fix it fast
1Find out which cause you have
Find out which image the failing command runs in. Start a shell in the image that failed, or the last stage of the Dockerfile, and ask for node and npm.
docker run --rm -it --entrypoint sh my-image # inside the container: command -v node command -v npm2Match what you see, then jump to its fix
- 1
The first FROM line is an image such as ubuntu, debian, python, php or nginx, and the failing line is RUN npm ...The base image does not contain Node.jsFix - 2
The build gets through npm ci and npm run build, then a later stage or the finished container fails with npm: not foundnpm is in an earlier build stage, but the command runs in a later oneFix - 3
A RUN line installs nvm and a Node version successfully, and the next RUN line says npm: not found or nvm: not foundNode.js was installed with nvm, which later RUN lines cannot seeFix
- 1
What does the error look like?
npm: not foundnpm: command not foundnvm: command not found
Cause 1 of 3
The base image does not contain Node.js
1Check
Read the FROM lines of the Dockerfile. The node README states that all node images ship with node and its npm. Other base images carry neither.
grep -n "^FROM" Dockerfile2Fix
Build on a node image, so node and npm are already there. Pick the version you run in development.
FROM node:24
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npm", "start"]3Verify
Rebuild, then ask the image itself for its npm version.
docker build -t my-nodejs-app .
docker run --rm my-nodejs-app npm -vConfirmed by github.com
Cause 2 of 3
npm is in an earlier build stage, but the command runs in a later one
1Check
Each FROM starts a new stage with its own base image, and only what you COPY --from carries over. A final stage built on nginx or another small image has no npm, so CMD npm start or a RUN npm line in it fails.
grep -n -E "^(FROM|RUN npm|CMD|ENTRYPOINT|COPY --from)" Dockerfile2Fix
Run every npm command in the stage that has Node.js. Copy only the result into the last stage and start it with a command that stage owns.
FROM node:24 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM nginx:stable
COPY --from=build /app/dist /usr/share/nginx/html3Verify
Build the last stage and confirm the container starts. A stage name lets you stop at an earlier stage when you need to debug it.
docker build -t my-site .
docker build --target build -t my-site-build .Confirmed by docs.docker.com
Cause 3 of 3
Node.js was installed with nvm, which later RUN lines cannot see
1Check
nvm is a shell function loaded from nvm.sh, not a program on PATH. The nvm README says a non-interactive shell, like the ones in a Docker build, does not read the profile files that load nvm.
grep -n -i "nvm" Dockerfile2Fix
The simplest fix is to drop nvm and use a node image. If you must keep nvm, source nvm.sh in the same RUN line that uses Node, as the nvm README does for its CI example.
ENV NVM_DIR="${HOME:-/root}/.nvm"
ENV NODE_VERSION=24
RUN bash -c "source $NVM_DIR/nvm.sh && nvm install $NODE_VERSION"
RUN bash -c "source $NVM_DIR/nvm.sh && npm ci"3Verify
The build passes the lines that failed before.
docker build --no-cache -t my-nodejs-app .Confirmed by github.com
How do I stop it coming back?
- Start Node.js projects from a node image, and use the same major version as local development.
- In a multi-stage Dockerfile, name each stage and keep every npm command in the stage built from a node image.
- Pin the base image to a full major tag such as node:24 instead of a floating tag, so the image does not change under you.
- Print node -v and npm -v in the build log once, so a wrong image shows up in the first few lines.
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.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
npm install fails inside a node:alpine Docker build
Docker Node Alpine Image Build Fails on node-gyp
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.
2 causes, each with a fixServers
Docker rebuilds reinstall every npm package on each build
npm install takes minutes after a one-line code change
Docker reuses a layer only if its inputs are unchanged.
3 causes, each with a fixBack end
Node.js in Docker Compose cannot reach MySQL on 127.0.0.1:3306
Error: connect ECONNREFUSED 127.0.0.1:3306
Inside a container, 127.0.0.1 is that container, not MySQL.
3 causes, each with a fixBack end
ECS task stops with exec format error on start
exec /usr/local/bin/docker-entrypoint.sh: exec format error
The container's binary was built for another CPU than the task runs on.
2 causes, each with a fixBack end
Kong Gateway returns 502 'An invalid response was received from the upstream server'
upstream sent too big header while reading response header from upstream
Kong returns 502 when it cannot get a valid HTTP response from the upstream.
4 causes, each with a fixBack end
Node.js cannot connect to MongoDB: ECONNREFUSED on port 27017
MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017
ECONNREFUSED means nothing accepted the connection at that address and port.
4 causes, each with a fix