Docker has transformed the way developers build, package, and deploy applications. However, traditional Docker images can often become unnecessarily large because they include build tools, development dependencies, source code, and other files that are not required in production. 

This is where Docker multi-stage builds become useful. 

A multi-stage Docker build allows developers to use multiple FROM statements in a single Dockerfile. One stage can be used to build or compile the application, while another stage contains only the files required to run it. 

The result is a smaller, cleaner, and more secure production image. 

What Is a Docker Multi-Stage Build? 

A Docker multi-stage build is a technique that uses multiple stages within a single Dockerfile. 

Each stage can use a different base image and serve a specific purpose. For example: 

• The first stage installs dependencies and builds the application. 

• The second stage copies only the required build output. 

• The final image contains only the runtime environment and production files. 

This approach helps remove unnecessary build tools, source files, and dependencies from the final container image. 

Basic Structure of a Multi-Stage Docker Build 

FROM node:20-alpine AS builder 
 
WORKDIR /app 
 
COPY package*.json ./ 
RUN npm ci 
 
COPY . . 
RUN npm run build 
 
 
FROM nginx:alpine 
 
COPY --from=builder /app/build /usr/share/nginx/html 
 
EXPOSE 80 
 
CMD ["nginx", "-g", "daemon off;"] 
 

In this example, the first stage builds the application, while the second stage uses Nginx to serve only the production-ready files. 

The build dependencies from the builder stage are not included in the final image. 

Why Are Docker Multi-Stage Builds Important? 

Large container images can create several challenges, including: 

• Longer image build times 

• Increased storage requirements 

• Slower deployments 

• Larger security attack surfaces 

• Unnecessary development dependencies in production 

Multi-stage builds help solve these problems by separating the build environment from the production runtime environment. 

Instead of deploying an image containing Node.js, build tools, package managers, source code, and dependencies, the final image can contain only the application artifacts needed to run the software. 

How Does a Docker Multi-Stage Build Work? 

The process generally follows these steps: 

1. Create a build stage 

Install development dependencies and compile or build the application. 

1. Generate production artifacts 

Create files such as compiled binaries, static assets, or application build folders. 

1. Create a new runtime stage 

Use a lightweight production-ready base image. 

1. Copy only required files 

Use the COPY --from command to transfer build artifacts from the previous stage. 

1. Run the final application 

Deploy the smaller and cleaner container image. 

Advantages of Docker Multi-Stage Builds 

1. Smaller Docker Images

One of the biggest benefits is reduced image size. 

Build tools, temporary files, package managers, source files, and development dependencies can remain in the build stage instead of being included in the final production image. 

Smaller images can also improve: 

• Storage efficiency 

• Image transfer times 

• Deployment speed 

• Container startup performance 

 

2. Improved Security

The final production image contains fewer components. 

This can reduce the potential attack surface because unnecessary tools and dependencies are removed from the runtime environment. 

Using trusted and minimal base images can further improve container security. 

3. CleanerDockerfiles

Multi-stage builds allow developers to define the complete build and production workflow inside a single Dockerfile. 

This makes container configuration easier to manage compared to maintaining separate Dockerfiles for development and production. 

4. Better CI/CD Integration

Docker multi-stage builds work well with automated CI/CD pipelines. 

The build process can compile the application, run required steps, create production artifacts, and generate a deployment-ready container image. 

This makes the deployment workflow more consistent and repeatable. 

5. Efficient Docker Layer Caching

Docker can reuse cached layers when the instructions and files involved have not changed. 

For example, copying dependency files before copying the complete application can help avoid reinstalling dependencies during every build. 

COPY package*.json ./ 
RUN npm ci 
 
COPY . . 
 

This structure can improve build efficiency when application code changes frequently but dependencies remain the same. 

6. Greater Flexibility

Different stages can use different base images depending on the requirements. 

For example, an application may use: 

• Node.js for building 

• Go for compilation 

• Maven for Java builds 

• Nginx for serving static files 

The final image does not need to contain all these tools. 

Disadvantages of Docker Multi-Stage Builds 

Although multi-stage builds offer many benefits, there are also some challenges. 

1. More ComplexDockerfiles

A multi-stage Dockerfile can be more difficult to understand than a basic single-stage Dockerfile. 

Developers need to carefully manage stages, dependencies, and file paths. 

2. Dependency Management Requires Care

Only the required production files should be copied into the final stage. 

Incorrect dependency handling can cause the application to fail during runtime. 

3. Debugging Can Be More Challenging

Because the final image is intentionally minimal, debugging tools may not be available inside the production container. 

Teams may need separate debugging or development environments. 

How to Create a Docker Multi-Stage Build for a React Application 

Let's look at a common example using React and Nginx. 

Step 1: Create the React Application Build 

The first stage uses Node.js to install dependencies and build the React application. 

FROM node:20-alpine AS builder 
 
WORKDIR /app 
 
COPY package*.json ./ 
 
RUN npm ci 
 
COPY . . 
 
RUN npm run build 
 

This stage creates the production build of the React application. 

Depending on the React framework or build tool, the output directory may be named build or dist. 

Step 2: Add the Production Stage 

The second stage uses a lightweight Nginx image to serve the generated static files. 

FROM nginx:alpine 
 
COPY --from=builder /app/build /usr/share/nginx/html 
 
EXPOSE 80 
 
CMD ["nginx", "-g", "daemon off;"] 
 

The final image does not contain the Node.js development environment or source dependencies from the builder stage. 

Complete Dockerfile Example 

# Build Stage 
FROM node:20-alpine AS builder 
 
WORKDIR /app 
 
COPY package*.json ./ 
 
RUN npm ci 
 
COPY . . 
 
RUN npm run build 
 
 
# Production Stage 
FROM nginx:alpine 
 
COPY --from=builder /app/build /usr/share/nginx/html 
 
EXPOSE 80 
 
CMD ["nginx", "-g", "daemon off;"] 
 

You can build the Docker image using: 

docker build -t react-multistage-app:latest . 
 

To run the container: 

docker run --rm -p 3001:80 react-multistage-app:latest 
 
 

Using a .dockerignore File 

A .dockerignore file helps prevent unnecessary files from being copied into the Docker build context. 

For example: 

node_modules 
.git 
.gitignore 
Dockerfile 
README.md 
npm-debug.log 
.env 
 

This can help reduce the build context size and improve build performance. 

Docker Multi-Stage Build Best Practices 

To get the best results from multi-stage Docker builds, consider the following practices. 

Use Minimal Base Images 

Choose lightweight and trusted base images whenever possible. 

For example: 

node:20-alpine 
nginx:alpine 
 

However, always ensure that the selected image is compatible with your application and security requirements. 

Use Specific Image Versions 

Avoid using only the latest tag for production deployments. 

Instead, use specific versions where possible. 

FROM node:20-alpine 
 

This helps create more predictable and reproducible builds. 

Copy Only Required Files 

Use COPY --from=builder to copy only the necessary build artifacts into the final image. 

Avoid copying unnecessary source files or development dependencies. 

Optimize Docker Layer Caching 

Copy dependency files before copying the entire application. 

COPY package*.json ./ 
RUN npm ci 
 
COPY . . 
 

This can help Docker reuse cached dependency layers. 

Use Multi-Stage Builds for Production 

Multi-stage builds are especially useful when the build environment requires tools that are not needed at runtime. 

Examples include: 

• React and Angular applications 

• Java applications 

• Go applications 

• Python applications with build dependencies 

• Compiled libraries 

• Microservices 

• CI/CD pipelines 

 

When Should You Use Docker Multi-Stage Builds? 

Multi-stage builds are particularly useful when your application requires a separate build and runtime environment. 

You should consider using them when: 

• Your Docker images are too large.
• Build tools are not required in production.
• You want to improve container security.
• Your application has a compilation process.
• You use automated CI/CD pipelines.
• You want faster image transfers and deployments.

 

However, not every application requires a multi-stage Docker build. For very simple applications, a single-stage Dockerfile may be easier to maintain. 

Docker Multi-Stage Build FAQs 

1. Whatisa multi-stage build in Docker? 

A Docker multi-stage build uses multiple FROM statements within a single Dockerfile. Each stage performs a specific task, such as building, compiling, testing, or running the application. 

2. What is the main benefit of Docker multi-stage builds?

The main benefit is that they reduce the size of the final Docker image by excluding unnecessary build tools, source files, and development dependencies. 

3. Does Docker multi-stage build improve security?

Yes. Multi-stage builds can improve security by reducing the number of unnecessary components included in the final production image, which can help reduce the container's attack surface. 

4. Can I use different base images in different Docker stages?

Yes. Each stage can use a different base image. For example, you can use Node.js to build an application and Nginx to serve the final static files. 

5. What doesCOPY --fromdo in Docker? 

The COPY --from=<stage-name> command copies files from one build stage into another stage. 

For example: 

COPY --from=builder /app/build /usr/share/nginx/html 
 

This copies only the required build output from the builder stage into the final Nginx image. 

6. Does Docker keep all stages in the final image?

No. In a typical multi-stage build, the final image contains only the files copied into the final stage. Previous build stages are not included in the resulting production image. 

7. Are Docker multi-stage builds useful for CI/CD?

Yes. Multi-stage builds work well with CI/CD pipelines because they create consistent and repeatable build and deployment processes. 

8. Can multi-stage Docker builds reduce deployment time?

They can help reduce deployment and transfer time when they significantly reduce the final image size. Smaller images generally require less data to be transferred and stored. 

Conclusion 

Docker multi-stage builds provide an effective way to create smaller, cleaner, and more secure container images. 

By separating the build environment from the production runtime, developers can remove unnecessary tools and dependencies from the final image. This approach can improve deployment efficiency, simplify container management, and support more reliable CI/CD workflows. 

Multi-stage builds are especially valuable for modern applications that require compilation, bundling, or other build-time processes. However, teams should carefully structure their Dockerfiles, manage dependencies correctly, and copy only the files required for production. 

If your organization is looking to optimize Docker environments, streamline CI/CD pipelines, or modernize cloud infrastructure, CloudStakes can help you build efficient and scalable DevOps and cloud solutions.