Maaz Zindani

Loading the index…

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

A Docker build or container says npm: not found

Errornpm: not found

Short 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.

  • Applies to Node.js 24, node:24 image
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 npm
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 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. 3A 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

What does the error look like?

  • npm: not found
  • npm: command not found
  • nvm: 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" Dockerfile

2Fix

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 -v

Confirmed by github.com

Did this fix it?

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)" Dockerfile

2Fix

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/html

3Verify

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

Did this fix it?

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" Dockerfile

2Fix

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

Did this fix it?

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:

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 fix

Next step

Want this handled for good?

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