Docker is a powerful tool for containerization, allowing developers to package their applications and dependencies into portable and lightweight containers. One of the key features of Docker is the ability to build Docker images, which serve as the blueprints for running containers. In this tutorial, we will explore the concept of multi-stage builds in Docker and how they can be used to streamline the build process and create optimized Docker images.

Understanding Docker Images and Dockerfiles

Before we dive into multi-stage builds, let’s first understand what Docker images and Dockerfiles are. A Docker image is a lightweight, standalone, and executable software package that includes everything needed to run a piece of software, including the code, a runtime, libraries, environment variables, and config files. A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image. Using docker build users can create an automated build that executes several command-line instructions in succession.

What are Multi-stage Builds?

Multi-stage builds are a feature introduced in Docker 17.05 that allow you to create multiple build stages within a single Dockerfile. Each stage can have its own set of instructions and dependencies, and the final image only includes the artifacts from the last stage. This allows you to separate the build environment from the runtime environment, resulting in smaller and more efficient Docker images. For more information, you can check out the official Docker documentation on multi-stage builds.

Benefits of Multi-stage Builds

Using multi-stage builds in Docker offers several benefits:

  • Smaller image size: By separating the build environment from the runtime environment, you can eliminate unnecessary dependencies and reduce the size of your Docker images.
  • Faster build times: With multi-stage builds, you can parallelize the build process and only include the necessary artifacts in the final image, resulting in faster build times.
  • Improved security: By removing build-time dependencies from the final image, you can reduce the attack surface and improve the security of your Docker containers.

Configuring Multi-stage Builds

To configure multi-stage builds in Docker, you need to define multiple build stages in your Dockerfile. Each stage is defined using the FROM keyword, followed by the base image for that stage. Here’s an example:

# Stage 1: Build stage
FROM node:14 as build
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Stage 2: Runtime stage
FROM nginx:latest
COPY --from=build /app/build /usr/share/nginx/html
CMD ["nginx", "-g", "daemon off;"]

In the above example, we have two stages: the build stage and the runtime stage. The build stage uses the Node.js base image to install dependencies, build the application, and generate the necessary artifacts. The runtime stage uses the Nginx base image and copies the artifacts from the build stage into the appropriate directory. Finally, it exposes port 80 and starts the Nginx server.

Building and Running the Multi-stage Build

To build the multi-stage Docker image, you can use the docker build command:

docker build -t myapp:latest .

This command builds the Docker image using the Dockerfile in the current directory and tags it with the name myapp:latest. The dot at the end of the command specifies the build context, which includes all the files in the current directory.

To run the Docker image, you can use the docker run command:

docker run -p 80:80 myapp:latest

This command runs the Docker image and maps port 80 of the host to port 80 of the container, allowing you to access the application in a web browser.

Advanced Multi-stage Build Patterns

While the basic multi-stage build process is straightforward, there are several advanced patterns that you can use to further optimize your Docker images and build process. These include:

  • Using builder pattern: This involves using a separate build stage to compile your application and then copying the compiled code into the final image. This can significantly reduce the size of the final image.
  • Using multi-stage builds for testing: You can use a separate stage in your Dockerfile for running tests. This allows you to include testing tools and frameworks in your build process without including them in the final image.
  • Using multi-stage builds for generating assets: If your application requires assets to be generated during the build process (such as CSS or JavaScript files), you can use a separate stage to generate these assets and then copy them into the final image.

Frequently Asked Questions

Here are some common questions about multi-stage builds in Docker:

1. Can I use different base images for different stages?

Yes, you can use different base images for different stages in a multi-stage build. This allows you to use the most appropriate tools and dependencies for each stage of the build process.

2. How can I copy files from one stage to another?

You can use the COPY --from command to copy files from one stage to another. For example, COPY --from=build /app/build /usr/share/nginx/html copies the build artifacts from the build stage to the runtime stage.

3. Can I use multi-stage builds with Docker Compose?

Yes, you can use multi-stage builds with Docker Compose. You just need to specify the target stage in the Docker Compose file. For more information, check out the Docker Compose documentation on build configuration.


Multi-stage builds in Docker provide a powerful way to optimize your Docker images and improve the efficiency of your build process. By separating the build environment from the runtime environment, you can create smaller, faster, and more secure Docker images. Start using multi-stage builds in your Docker projects and experience the benefits for yourself!