4.3.1.2 Manifest Copy Order

Manifest copy order is the specific practice of copying a dependency manifest file (such as package.json or requirements.txt) into the build context before copying the rest of an application's source code, positioned deliberately ahead of the dependency installation step to maximize cache reuse.

The Pattern in Detail

Copying only the manifest first, installing dependencies based on it, and only then copying the remaining application source isolates the (often slow) dependency installation step from unrelated source code changes.

COPY package.json package-lock.json ./
RUN npm install
COPY . .

If a later build only changes application source files, this ordering means npm install is served entirely from the build cache, since the manifest files it depends on are unchanged.

Why Order Specifically Matters Here

Reversing this order — copying everything first, then installing — would cause Docker's cache to invalidate the dependency installation step on every single source code change, even ones that have nothing to do with dependencies.

COPY . .
RUN npm install

COPY package.json package-lock.json ./
RUN npm install
COPY . .

The second ordering is strictly better for cache efficiency in nearly every realistic development workflow, where source code changes far more often than declared dependencies do.

Applying the Pattern Across Ecosystems

The same manifest-first copy pattern applies with minor variations across virtually every language ecosystem with its own dependency manager.

COPY go.mod go.sum ./
RUN go mod download
COPY . .

COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .

Verifying the Pattern's Effect

Measuring build time for a source-only change confirms whether the manifest copy order is actually preserving the intended caching benefit in practice.

echo "// minor change" >> src/index.js
time docker build -t myapp .

Why Manifest Copy Order Matters

This single, broadly applicable pattern is one of the most impactful and easiest-to-adopt build optimizations available, directly reducing average build time for the overwhelming majority of everyday development iterations across nearly any language ecosystem.