How to Build Slim and Fast Docker Images with Multi-Stage Builds

Apps don’t stay simple forever. More features mean more dependencies, slower builds, and heavier Docker images. That’s where things start to hurt.

Docker helps, but without the right setup, your builds can quickly get bloated.

Multi-stage builds make things smoother by keeping your images fast, clean, and production-ready. In this guide, you’ll learn how to use them to supercharge your Docker workflow.

Let’s get into it.

Prerequisites

To follow this guide, you should have:

• Docker installed and running

• Basic understanding of Docker

• Some Python knowledge (or any language, really)

• Familiarity with the terminal

Here’s what we’ll cover:

1. What are Docker Images?

2. How to Implement Multi-Stage Builds

3. The Chunky Single-Stage Build

4. When to Use Multi-Stage Builds

5. Conclusion

What are Docker Images?

Before we dive into optimization, let’s quickly get clear on what Docker images actually are.

A Docker image is a lightweight, standalone package that has everything your app needs to run – code, dependencies, environment variables, and config files. Think of it as a snapshot of your app, ready to spin up anywhere.

When you run an image, Docker turns it into a container: a self-contained environment that behaves the same on your machine, in staging, or in production. That consistency is a huge win for development and deployment.

Now that we’ve got the basics, let’s talk about making those images smaller and faster.

How to Implement Multi-Stage Builds

Let’s get hands-on by creating a basic Flask app and using a multi-stage build to keep our Docker image slim.

Step 1: Create app.py

<span class="hljs-keyword">from</span> flask <span class="hljs-keyword">import</span> Flask

app = Flask(__name__)

<span class="hljs-meta">@app.route('/')</span>
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">hello</span>():</span>
    <span class="hljs-keyword">return</span> <span class="hljs-string">"Hello, Docker Multi-stage Builds! 🐳"</span>

<span class="hljs-keyword">if</span> __name__ == <span class="hljs-string">'__main__'</span>:
    app.run(host=<span class="hljs-string">'0.0.0.0'</span>, port=<span class="hljs-number">5000</span>)

Step 2: Install and save dependencies

Install Flask and Gunicorn using pip:

pip install flask gunicorn

Then freeze your environment into a requirements.txt file:

pip freeze > requirements.txt

This file is what Docker will use to install dependencies inside your container.

Step 3: Create the multi-stage Dockerfile

<span class="hljs-comment"># Stage 1: Build Stage</span>
<span class="hljs-keyword">FROM</span> python:<span class="hljs-number">3.9</span>-slim AS builder

<span class="hljs-keyword">WORKDIR</span><span class="bash"> /app</span>

<span class="hljs-keyword">COPY</span><span class="bash"> requirements.txt .</span>

<span class="hljs-keyword">RUN</span><span class="bash"> python -m venv /opt/venv && \
    . /opt/venv/bin/activate && \
    pip install --no-cache-dir -r requirements.txt</span>

<span class="hljs-comment"># Stage 2: Production Stage</span>
<span class="hljs-keyword">FROM</span> python:<span class="hljs-number">3.9</span>-slim

<span class="hljs-keyword">COPY</span><span class="bash"> --from=builder /opt/venv /opt/venv</span>

<span class="hljs-keyword">WORKDIR</span><span class="bash"> /app</span>

<span class="hljs-keyword">COPY</span><span class="bash"> . .</span>

<span class="hljs-keyword">ENV</span> PATH=<span class="hljs-string">"/opt/venv/bin/:$PATH"</span>

<span class="hljs-keyword">EXPOSE</span> <span class="hljs-number">5000</span>

<span class="hljs-keyword">CMD</span><span class="bash"> [<span class="hljs-string">"gunicorn"</span>, <span class="hljs-string">"--bind"</span>, <span class="hljs-string">"0.0.0.0:5000"</span>, <span class="hljs-string">"app:app"</span>]</span>

In the Dockerfile above, we’ve defined both a development and a production stage for our application. The first stage, the Build Stage, uses the python:3.9-slim base image, sets up a working directory, adds all the necessary files, and creates a virtual environment. All dependencies are installed inside that virtual environment.

In the Production Stage, we again start from python:3.9-slim, but this time we copy only the virtual environment from the build stage along with the application code. Then we configure the environment to use that virtual environment and run the app using Gunicorn.

Now, in a multi-stage build, you can experiment with using different Python versions across stages – but here’s why I didn’t go that route:

• Some packages may have different dependencies, depending on the Python version.

• My requirements.txt file contains version-specific dependencies, so sticking to the same Python version across both stages helps avoid compatibility issues.

Once the multi-stage Dockerfile is ready, go ahead and build the images. You’ll clearly see the size difference.

Step 4: Build and run your image

To build and run your image container, use the following command:

<span class="hljs-comment"># Build the image</span>
docker build -t my-python-app .

<span class="hljs-comment"># Run the container</span>
docker run -p 5000:5000 my-python-app

If everything works correctly, your Flask app should now be live at http://localhost:5000 in your browser.

You’ll know your build succeeded when Docker completes without errors and starts the container. You should see terminal logs from Gunicorn indicating the app is up and running.

The Chunky Single-Stage Build

Let’s compare with a traditional one-stage Docker build that includes everything in one go:

<span class="hljs-keyword">FROM</span> python:<span class="hljs-number">3.9</span>-slim

<span class="hljs-keyword">WORKDIR</span><span class="bash"> /app</span>

<span class="hljs-keyword">RUN</span><span class="bash"> apt-get update && apt-get install -y \
    build-essential \
    python3-dev \
    gcc \
    && rm -rf /var/lib/apt/lists/*</span>

<span class="hljs-keyword">COPY</span><span class="bash"> requirements.txt .</span>

<span class="hljs-keyword">RUN</span><span class="bash"> python -m venv /opt/venv</span>
<span class="hljs-keyword">ENV</span> PATH=<span class="hljs-string">"/opt/venv/bin:$PATH"</span>

<span class="hljs-keyword">RUN</span><span class="bash"> pip install --no-cache-dir -r requirements.txt</span>

<span class="hljs-keyword">COPY</span><span class="bash"> . .</span>

<span class="hljs-keyword">EXPOSE</span> <span class="hljs-number">5000</span>

<span class="hljs-keyword">CMD</span><span class="bash"> [<span class="hljs-string">"gunicorn"</span>, <span class="hljs-string">"--bind"</span>, <span class="hljs-string">"0.0.0.0:5000"</span>, <span class="hljs-string">"app:app"</span>]</span>

The Dockerfile above uses a straightforward build process: it starts from the python:3.9-slim image, sets a working directory, installs system dependencies, creates a virtual environment, installs Python packages, copies over the app code, exposes port 5000, and runs the app using Gunicorn. This kind of Dockerfile is common and works fine, but it can lead to unnecessarily large and bloated images.

Let’s build our image to compare the size with that of the multi-stage build:

docker build -t my-chunky-app .

You’ll notice that this Dockerfile takes longer to build compared to the previous one, which was much faster.

Before we continue, confirm your Docker image was successfully built.

Now, let’s compare build sizes:

docker images | grep <span class="hljs-string">'my-'</span>

In case you’re wondering why we used “my” to search for the images, it’s because we named our Docker images my-python-app and my-chunky-app, so using “my” as a keyword makes it easy to filter them.

The image above compares the build sizes of our single-stage and multi-stage Docker images. As you can see, my-python-app – the multi-stage build – is small and lightweight, while my-chunky-app is significantly larger. If you dig a bit deeper, you’ll notice that the multi-stage image built in just 1.2 seconds, whereas the single-stage one took a full 1 minute and 21 seconds. Pretty impressive difference, right?

In my opinion, these are solid reasons to use a multi-stage build – but it’s not always necessary. There are cases where a single-stage build makes more sense. Let’s take a look at those.

When to Use Multi-Stage Builds

Use multi-stage builds if:

• Your app needs build tools (for example, compilers, dev dependencies)

• You want smaller, faster Docker images

• You care about image security and performance

Use single-stage builds if:

• You’re just testing or prototyping

• Your app is tiny and doesn’t need external tools

• You’re still learning the basics

Pick what fits your project’s scale and complexity.

Conclusion

Multi-stage builds are an easy win. They help keep your Docker images clean, fast, and secure – especially as your app grows.

Not every project needs them, but when you do, they make a big difference. So next time you’re Dockerizing something serious, reach for multi-stage. Your future self will thank you.

Source: freeCodeCamp Programming Tutorials: Python, JavaScript, Git & More