Why multi-stage builds reduce image size in Docker - Visual Breakdown

Process Flow - Why multi-stage builds reduce image size

Start: Base Build Stage

↓

Install dependencies & build app

↓

Start: Final Stage

↓

Copy only built app from build stage

↓

Create smaller final image

↓

Result: Reduced image size

The build process uses one stage to compile and prepare the app, then copies only the needed files to a smaller final stage, reducing image size.

Execution Sample

Docker

FROM node:18 AS build
WORKDIR /app
COPY package.json .
RUN npm install
COPY . .
RUN npm run build

FROM node:18-slim
WORKDIR /app
COPY --from=build /app/package.json ./
RUN npm install --production
COPY --from=build /app/dist ./dist
CMD ["node", "dist/index.js"]

This Dockerfile builds the app in a full node image (with dev deps), then copies package.json to install production deps only and copies the built files to a smaller node-slim image.

Process Table

Step	Action	Stage	Files Present	Image Size Impact
1	Start build stage with full node image	build	Base Node runtime & tools	Large size due to full tools
2	Install dependencies and build app	build	Source + node_modules + build output	Size grows with dependencies and build artifacts
3	Start final stage with slim node image	final	Empty except base slim image	Small base size
4	Copy package.json & build output from build stage, install prod deps	final	package.json + prod node_modules + /app/dist	Small size, no dev dependencies or source code
5	Set command to run built app	final	Built app ready to run	Final image size is minimal
6	Image build complete	final	Only runtime files	Reduced image size compared to single stage
7	Exit	-	-	Build finished, smaller image created

💡 Build finishes after copying only necessary files to final stage, reducing image size

Status Tracker

Variable	Start	After Step 2	After Step 4	Final
Files Present	Empty	Source + node_modules + build output	package.json + prod node_modules + build output (/app/dist)	package.json + prod node_modules + build output (/app/dist)
Image Size	Base slim image size	Large (full node + deps)	Small (slim + prod deps + build output)	Small (slim + prod deps + build output)

Key Moments - 3 Insights

Why does the final image not include node_modules from the build stage?

Because package.json and only the built output folder (/app/dist) are copied from the build stage to the final stage (prod node_modules installed separately), excluding build stage node_modules (dev + prod) and source files as shown in execution_table step 4.

Why is the build stage image larger than the final image?

The build stage includes all source code, dependencies, and build tools, making it large (step 2), while the final stage copies only the minimal runtime files (step 4), reducing size.

What happens if we copy everything from the build stage to the final stage?

The final image size would be large, similar to the build stage, losing the benefit of multi-stage builds as explained in the exit note and step 6.

Visual Quiz - 3 Questions

Look at the execution table, at which step are only the built app files copied to the final image?

A Step 2

B Step 4

C Step 1

D Step 6

💡 Hint

Check the 'Action' and 'Files Present' columns in execution_table row for step 4.

According to variable_tracker, what happens to the image size after step 4?

A It becomes larger

B It stays the same

C It becomes smaller

D It is empty

💡 Hint

Look at the 'Image Size' row values after step 4 in variable_tracker.

If we copied node_modules to the final stage, how would the final image size change?

A It would be larger

B It would be smaller

C It would stay the same

D It would be empty

💡 Hint

Refer to key_moments question about copying everything and execution_table step 2 vs step 4.

Concept Snapshot

Multi-stage builds use separate stages to build and package apps.
The build stage includes all tools and dependencies.
The final stage copies only needed files (like package.json & build output).
This reduces final image size by excluding dev files.
Use COPY --from=build to transfer files between stages.

Full Transcript

Multi-stage builds in Docker help reduce image size by separating the build environment from the final runtime environment. First, a build stage uses a full image with all dependencies and tools to compile the app. Then, a final stage starts from a smaller base image, copies package.json to install production deps only, and copies only the built app files from the build stage. This way, the final image excludes unnecessary files like source code and dev node_modules, making it much smaller. The execution table shows each step: starting the build stage, installing dependencies, building the app, starting the final stage, copying necessary files & installing prod deps, and finishing with a small image. The variable tracker highlights how files and image size change after each step. Key moments clarify why only specific files are copied and why the build stage is larger. The visual quiz tests understanding of these steps and their effects. Overall, multi-stage builds are a simple and effective way to keep Docker images lean.