Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Docker rebuilds reinstall every npm package on each build

ErrorRUN npm install runs on every build instead of CACHED

Short answer

Docker reuses a layer only if its inputs are unchanged. If the install step comes after COPY of the whole project, any edited file invalidates it. Copy only package files first, run the install, then copy the source. Add a .dockerignore and a cache mount to speed up the cases that still rebuild.

  • Applies to Docker Engine 27, BuildKit, Node.js 22, npm 10
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Build twice with plain progress output and see which step is not marked CACHED. The first uncached step is the one that broke the chain.

    docker build --progress=plain -t my-app . 2>&1 | grep -E 'CACHED|RUN|COPY'
  2. 2Match what you see, then jump to its fix

    1. 1COPY . . appears above RUN npm install in the DockerfileThe whole project is copied before npm installFix
    2. 2Sending build context is large, and COPY . . is never cachednode_modules and other local files are sent in the build contextFix
    3. 3The install step is correctly placed but runs after each dependency change, and downloads everythingThe install layer has to rebuild, and every package is downloaded againFix

What does the error look like?

  • RUN npm install runs on every build instead of CACHED
  • npm install takes minutes after a one-line code change

Cause 1 of 3

The whole project is copied before npm install

1Check

A change to any file invalidates the cache for every step after it. With the full copy first, an edited source file forces a new install.

grep -n -E 'COPY|RUN npm' Dockerfile

2Fix

Copy the package manifest and lock file, install, and copy the rest afterwards. Use npm ci so the lock file is respected.

FROM node:22
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .

3Verify

Change one source file and rebuild; the install step should say CACHED.

echo "// touch" >> src/index.js
docker build --progress=plain -t my-app . 2>&1 | grep "npm ci"

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

node_modules and other local files are sent in the build context

1Check

Without a .dockerignore, the context includes your local node_modules and temp files, which change often and invalidate the copy step.

ls -a | grep dockerignore; du -sh node_modules

2Fix

Add a .dockerignore next to the Dockerfile so those paths are left out.

# .dockerignore
node_modules
tmp*
.git

3Verify

The context upload shrinks and the copy step stays cached when nothing relevant changed.

docker build --progress=plain -t my-app . 2>&1 | grep -i 'transferring context'

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The install layer has to rebuild, and every package is downloaded again

1Check

A normal layer cache is all or nothing. When package-lock.json changes, npm starts with an empty cache inside the build.

grep -n 'mount=type=cache' Dockerfile

2Fix

Mount a persistent cache for npm's folder. Docker names /root/.npm as the target for npm. Only changed packages are fetched.

# syntax=docker/dockerfile:1
RUN --mount=type=cache,target=/root/.npm npm ci

3Verify

Add one dependency, rebuild, and watch the install step finish faster than a cold build.

docker build --progress=plain -t my-app . 2>&1 | grep -A3 'npm ci'

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Keep the order: base image, package files, install, source, build.
  • Commit package-lock.json and use npm ci in images, so the install layer only changes when dependencies do.
  • Review the Dockerfile whenever someone adds a COPY line above the install.

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

Next step

Want this handled for good?

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