Reducing Docker Image Size

Reducing Docker image size is not only about storage but also about security and cloud cost and more…

A 10-line Python script does not need a 1 GB image. But that is exactly what you get when you write FROM python, then COPY . ., and call it a day. The image works, so nobody complains, until it has to be pulled onto a hundred machines. Here are the tricks I use to put my images on a diet.

Why Reduce Size

Techniques At A Glance

Lightweight Base Image

Your base image is usually the biggest part of your final image, so start here. Roughly (check yours with docker image ls, numbers move with versions):

Same story with Node: node, node:<version>-slim and node:<version>-alpine.

Why not Ubuntu for everything? If your app is Python, a ready-made python image already has Python set up, so you don’t install and clean it up yourself.

Why not always Alpine then? Because it is not a free lunch:

Remove Dev Dependencies

Production does not run your tests or linter, so don’t ship them. Keep two lists:

# requirements.txt (what the app needs to run)
requests==2.32.3

# requirements-dev.txt (extra stuff for you only)
-r requirements.txt
pytest
ruff

Your Dockerfile installs only requirements.txt. On your laptop you install the dev one.

Same idea elsewhere, for example npm: npm ci --omit=dev.

Clean Package Manager Caches

apt, pip and npm all keep downloaded files around “just in case”. In an image, nobody needs them.

# apt: skip suggested extras, delete package lists
RUN apt-get update \
    && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*

# pip: don't keep a cache at all
RUN pip install --no-cache-dir -r requirements.txt

# npm: clean after install
RUN npm ci --omit=dev && npm cache clean --force

Multi-Stage Build

Idea: do the messy work (compilers, caches, dev tools) in a first image, then start a fresh clean image and copy over only the result. Everything else is thrown away.

    flowchart LR
    builder["Builder Stage: compilers, pip, caches"] -->|"COPY --from=builder /opt/venv"| final["Final Stage: runtime + venv + app"]
    builder -.->|thrown away| trash["Discarded"]
  

Let’s see it with our own eyes. Create a folder with these files:

mkdir size-demo && cd size-demo

cat > app.py << EOF
import requests
print("requests version:", requests.__version__)
EOF

cat > requirements.txt << EOF
requests==2.32.3
EOF

The single-stage version, everything in one image:

FROM python:3.12-slim
RUN apt-get update \
    && apt-get install -y --no-install-recommends build-essential \
    && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
CMD ["python", "app.py"]

The multi-stage version, compilers stay in the builder:

FROM python:3.12-slim AS builder
RUN apt-get update \
    && apt-get install -y --no-install-recommends build-essential \
    && rm -rf /var/lib/apt/lists/*
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM python:3.12-slim
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app
COPY app.py .
CMD ["python", "app.py"]

Build both and compare:

docker image build -t size-single -f Dockerfile.single .
docker image build -t size-multi -f Dockerfile.multi .
docker image ls --filter "reference=size-*"

The multi-stage image should be much smaller, because the compilers never made it to the final stage. Both do the same job:

docker container run --rm size-multi

requests version: 2.32.3

Want to know where the weight is? Look at the layers:

docker image history size-single

Clean up:

docker image rm size-single size-multi
cd .. && rm -rf size-demo

Distroless

Even Alpine is still a small Linux, with a shell, a package manager and tools. Distroless images (from Google) throw all of that away and keep only your app and what it needs to run.

Debugging is harder, yes. But in almost all cases the end users are not there to debug, and a container is not a server you log into anyway.

Don’t Forget .dockerignore

A broad COPY . . copies everything in your folder: .git history, virtual environments, test data, and even .env or private key files. All of it can end up inside your image.

.git
__pycache__/
*.pyc
venv/
.venv/
node_modules/
.env
*.pem
*.key

This helps in two ways: smaller image, and secrets never enter the build at all.

A Few More Tricks

So that is my diet plan: a slim base, no dev stuff, clean as you go, ship only what you built, and keep junk out of the build. Run docker image ls before and after, and enjoy watching the number drop.