Docker Multi-Stage Builds: An In-depth Guide


Docker has revolutionized the way we develop, package, and deploy applications. It provides a consistent environment for applications to run, from development to production, reducing the “it works on my machine” problem. One of the most powerful features Docker has introduced is multi-stage builds. This feature helps us create lean, efficient containers without the usual hassle. In this blog post, we will delve into Docker multi-stage builds, their benefits, and best practices. We will also provide an example Dockerfile to illustrate the concept.

What is Docker Multi-Stage Build?

Docker multi-stage build is a feature that allows you to use multiple FROM statements in your Dockerfile. Each FROM statement can use a different base image and starts a new stage of the build. You can selectively copy artifacts from one stage to another, leaving behind everything you don’t need in the final image. This allows you to create smaller, more efficient images by separating the building and packaging processes into different stages.

Why Use Docker Multi-Stage Builds?

Before the introduction of multi-stage builds, creating lean Docker images was a bit of a hassle. You had to create separate Dockerfiles for building and running applications, or install unnecessary tools in your production images. Multi-stage builds solve these problems by allowing you to use one Dockerfile to create efficient images. Here are some reasons why you should use Docker multi-stage builds:

  1. Smaller Image Size: By copying only the necessary files from the build stage to the final image, you can significantly reduce the size of your Docker images. Smaller images are faster to push and pull from registries, and they use less disk space.
  2. Separation of Concerns: With multi-stage builds, you can separate the build-time dependencies from the runtime dependencies. This makes your Dockerfile easier to read and maintain.
  3. Security: Smaller images have a smaller attack surface. By excluding unnecessary tools and files, you reduce the potential for security vulnerabilities.

Best Practices

  1. Use Specific Base Images: For each stage, use the most specific base image that includes only what you need for that stage. For example, use a Node.js image for a build stage that involves a Node.js application, and an Alpine image for a lightweight final stage.
  2. Optimize Layer Creation: Docker builds images in layers. To make your builds faster and your images smaller, try to minimize the number of layers by combining commands using &&.
  3. Clean Up After Yourself: In the build stage, clean up unnecessary files and artifacts after you’re done with them. This will make the build cache smaller and faster.

Example Dockerfile

Here’s an example Dockerfile that demonstrates a multi-stage build for a Node.js application:


# ---- Base Node ----
FROM node:14 AS base
WORKDIR /usr/src/app
COPY package*.json ./

# ---- Dependencies ----
FROM base AS dependencies
RUN npm install

# ---- Test ----
# run linters, setup and tests
FROM dependencies AS test
COPY . .
RUN npm run test

# ---- Build ----
FROM dependencies AS build
COPY . .
RUN npm run build

# ---- Release ----
FROM node:14-alpine AS release
WORKDIR /usr/src/app
COPY --from=build /usr/src/app/dist ./dist
CMD ["node", "dist/index.js"]

In this Dockerfile, we have five stages: base, dependencies, test, build, and release. The base stage copies the package.json files. The dependencies stage installs the Node modules. The test stage runs the tests. The build stage builds the application. Finally, the release stage creates the final image that will be used in production. Only the necessary files are copied to the final image, resulting in a smaller, more efficient image.


Docker multi-stage builds are a powerful tool for creating efficient Docker images. They allow you to separate your build and runtime environments, reduce your image size, and improve security. By following best practices and using a well-structured Dockerfile, you can take full advantage of this feature. Happy Dockering!