← Back to DevBytes
Docker July 07, 2026 12 min read

Docker Image Optimization: Production Guide

What is Docker Image Optimization?

Docker image optimization is the practice of reducing the size, minimizing the attack surface, and improving the build performance of your container images. It involves a set of techniques and strategies applied during the Dockerfile authoring and build process to create lean, efficient, and secure images that are suitable for production deployment. An optimized image contains only the runtime dependencies necessary for the application to function — nothing more, nothing less.

At its core, optimization targets three key dimensions: image size (measured in megabytes), layer count and caching efficiency (affecting pull times and rebuild speed), and security posture (reducing CVEs and unnecessary binaries that could be exploited). A bloated image might include build tools, package manager caches, development headers, debugging utilities, and entire operating system distributions that are never used at runtime. Optimization strips these away systematically.

Why Image Optimization Matters in Production

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

In production environments, unoptimized images carry real, measurable costs. Here are the primary reasons why optimization should be a non-negotiable part of your containerization workflow:

Core Techniques for Optimizing Docker Images

1. Multi-Stage Builds

Multi-stage builds are the single most impactful optimization technique. They allow you to use one stage for compiling, building, or downloading dependencies, and then copy only the final artifacts into a clean, minimal runtime image. The build dependencies (compilers, SDKs, package managers, build tools) never appear in the final image.

Consider a Go application. Building it requires the Go SDK, but running it needs nothing but the compiled binary. Without multi-stage builds, you'd either ship the full Go SDK in your image or resort to fragile shell scripts to copy artifacts. With multi-stage builds, the solution is elegant:

# Stage 1: Build the Go binary
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /server ./cmd/server

# Stage 2: Minimal runtime image
FROM alpine:3.20
RUN apk --no-cache add ca-certificates
COPY --from=builder /server /usr/local/bin/server
EXPOSE 8080
CMD ["/usr/local/bin/server"]

The final image contains only the compiled binary and the CA certificates needed for TLS connections. The Go SDK, source code, and intermediate build artifacts are completely absent. This pattern applies universally — to Java (build with Maven/Gradle in one stage, copy the JAR), to Node.js (run webpack/esbuild in one stage, copy the dist folder), to C++ (compile in one stage, copy the binary).

2. Choosing the Right Base Image

The base image you select determines the floor for both size and vulnerability count. Here is a comparison of common base images and their approximate uncompressed sizes:

# Full OS images (avoid for production unless absolutely necessary)
ubuntu:24.04                     ~ 78 MB
debian:bookworm                  ~ 124 MB
centos:stream9                   ~ 170 MB

# Alpine-based images (good balance of size and compatibility)
alpine:3.20                      ~ 3 MB
golang:1.22-alpine               ~ 42 MB
node:20-alpine                   ~ 51 MB
python:3.12-alpine               ~ 28 MB

# Distroless images (minimal, no shell, no package manager)
gcr.io/distroless/static-debian12   ~ 2 MB
gcr.io/distroless/base-debian12     ~ 20 MB
gcr.io/distroless/nodejs20-debian12 ~ 35 MB

# Scratch (completely empty — no files, no shell, no CA certs)
FROM scratch                     ~ 0 MB

Alpine is a popular choice because it includes a package manager (apk) and a shell, making debugging easier, while still being tiny. Distroless images from Google remove even the shell and package manager, providing only the runtime dependencies for your language. Scratch is a blank filesystem — you must copy every single dependency yourself, including CA certificates and DNS libraries if your application needs them.

When selecting a base image, ask: Does your application need a shell? Does it need TLS? Does it need dynamic linking to glibc? Match your base image to these exact requirements.

3. Layer Optimization and Dockerfile Ordering

Docker images are composed of layers, and each instruction in a Dockerfile (RUN, COPY, ADD) creates a new layer. Layers are cached independently — if a layer hasn't changed, Docker reuses it from the build cache. This means the order of your instructions directly impacts how often layers must be rebuilt.

The golden rule: place instructions that change frequently (like copying application source code) as late as possible in the Dockerfile. Place instructions that change rarely (like installing system dependencies) as early as possible.

Compare these two Dockerfiles for a Node.js application:

# ❌ Bad: Source copy happens before npm install
FROM node:20-alpine
WORKDIR /app
COPY . .                    # Changes every commit — busts cache
RUN npm ci --only=production

# ✅ Good: Dependency installation happens first, source copy last
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production   # Cached unless package.json changes
COPY . .                       # Only this layer changes frequently

In the good example, if only the application source code changes (not the dependencies), the npm ci layer is fetched from cache instantly. The build only re-executes the final COPY . . step. This can reduce rebuild times from minutes to seconds.

4. Combining RUN Instructions and Cleaning Up

Each RUN instruction creates a separate layer. Even if you remove files in a later layer, they still exist in the previous layer and contribute to the total image size. To truly remove temporary files and package manager caches, you must clean them up within the same RUN instruction where they were created.

# ❌ Bad: The packages and cache persist in layer 1, even though layer 2 deletes them
RUN apt-get update && apt-get install -y gcc make curl
RUN apt-get clean && rm -rf /var/lib/apt/lists/*

# ✅ Good: Everything happens in one layer, nothing persists
RUN apt-get update \
    && apt-get install -y --no-install-recommends gcc make curl \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    && rm -rf /tmp/*

For Alpine's apk, the pattern is similar but with different flags:

RUN apk add --no-cache --virtual .build-deps \
    gcc musl-dev make \
    && make \
    && apk del .build-deps

The --virtual flag tags packages under a named group (.build-deps), and apk del removes that entire group in one clean operation — all within the same RUN instruction.

5. The .dockerignore File

Before the Docker build even begins, the entire build context (the directory you point Docker to) is sent to the Docker daemon. If you copy your entire project with COPY . . without a .dockerignore, you're likely including node_modules, .git, IDE configurations, test fixtures, log files, and local environment files. This bloats the build context, slows down the COPY instruction, and can inadvertently leak secrets into the image.

A well-crafted .dockerignore file for a typical project might look like:

# .dockerignore
.git
.gitignore
*.md
LICENSE
node_modules
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.env
.env.local
.env.*.local
*.log
*.tmp
.DS_Store
Thumbs.db
.vscode
.idea
*.swp
*.swo
coverage
dist
build
tests
test
__tests__
*.test.js
*.test.ts
*.spec.js
*.spec.ts
docker-compose*.yml
Dockerfile*
Makefile
README.md

Be explicit about what your application actually needs at runtime. If your build process compiles a dist directory, exclude the source files and include only the compiled output. The build context should be as minimal as possible.

6. Using Specific Image Tags and Digest Pinning

Using floating tags like node:latest or python:3 is dangerous for production — you may unknowingly pull a new major version with breaking changes or new vulnerabilities. Always pin to a specific minor version. For maximum reproducibility, pin to a digest hash:

# Good: Specific minor version
FROM node:20.11-alpine

# Better: Digest pinning for absolute reproducibility
FROM node:20.11-alpine@sha256:a1b2c3d4e5f6...

Digest pinning ensures that every build in your CI pipeline uses the exact same base image bytes, eliminating the "it works on my machine but not in CI" class of bugs caused by upstream image changes.

7. Avoiding Unnecessary Packages and Binaries

Audit every package installed in your final image. Ask: "Does my application use this at runtime?" Common candidates for removal include:

On Debian/Ubuntu, always use --no-install-recommends to avoid pulling in suggested packages:

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        ca-certificates \
        libssl3 \
    && rm -rf /var/lib/apt/lists/*

8. Leveraging Docker BuildKit and Advanced Features

Docker BuildKit (enabled by default in recent Docker versions) provides additional optimization capabilities. You can use RUN --mount=type=cache to persist package manager caches across builds without including them in the final image:

# BuildKit cache mount for apt
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates

# BuildKit cache mount for apk
RUN --mount=type=cache,target=/var/cache/apk \
    apk add --no-cache ca-certificates

You can also use COPY --link to copy files without invalidating subsequent layer caches when the source changes, and ADD --checksum to verify the integrity of downloaded artifacts.

9. Scanning and Analyzing Images

Optimization is an iterative process — you can't improve what you don't measure. Use these tools to inspect your images:

# Show image size and layers
docker images <image> --format "{{.Size}}"
docker history <image> --no-trunc --human

# Dive: interactive layer-by-layer exploration
dive <image>

# Docker-slim: automatic minification
docker-slim build --http-probe=false <image>

# Vulnerability scanning
trivy image <image>
grype <image>

# Show packages installed in the image
# For Debian-based images
docker run --rm --entrypoint dpkg <image> -l
# For Alpine-based images
docker run --rm --entrypoint apk <image> list

dive is particularly useful — it shows you exactly which files each layer introduced and highlights wasted space. docker-slim can automatically profile your application at runtime and produce a minimized image containing only the files actually accessed.

Complete Production Dockerfile Example

Here is a complete, production-grade Dockerfile that incorporates all the techniques discussed above. It builds a hypothetical Node.js Express API server:

# =============================================================================
# Stage 1: Install dependencies and build TypeScript
# =============================================================================
FROM node:20.11-alpine@sha256:abc123... AS builder

WORKDIR /app

# Copy dependency manifests first for layer caching
COPY package.json package-lock.json tsconfig.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci

# Copy source and compile
COPY src/ ./src/
RUN npm run build

# Prune dev dependencies from node_modules
RUN npm prune --production

# =============================================================================
# Stage 2: Create the production runtime image
# =============================================================================
FROM alpine:3.20.3@sha256:def456... AS runtime

# Install only the runtime dependencies needed by Node.js
RUN apk add --no-cache \
    ca-certificates \
    libstdc++ \
    libgcc \
    && addgroup -S app \
    && adduser -S app -G app

# Copy the Node.js runtime binary from the official image
COPY --from=node:20.11-alpine /usr/local/bin/node /usr/local/bin/node
COPY --from=node:20.11-alpine /usr/local/lib/node_modules /usr/local/lib/node_modules
COPY --from=node:20.11-alpine /usr/local/bin/docker-entrypoint.sh /usr/local/bin/
COPY --from=node:20.11-alpine /usr/lib/libssl.so.3 /usr/lib/
COPY --from=node:20.11-alpine /usr/lib/libcrypto.so.3 /usr/lib/

# Copy application artifacts from the builder stage
WORKDIR /home/app
COPY --from=builder --chown=app:app /app/dist ./dist
COPY --from=builder --chown=app:app /app/node_modules ./node_modules
COPY --from=builder --chown=app:app /app/package.json ./

# Set environment variables
ENV NODE_ENV=production
ENV PORT=8080

EXPOSE 8080
USER app

# Health check without requiring curl/wget (uses Node.js itself)
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD node -e "require('http').get('http://localhost:8080/health', (res) => { process.exit(res.statusCode === 200 ? 0 : 1) })"

CMD ["node", "dist/index.js"]

This Dockerfile demonstrates: multi-stage builds, cache mounts, specific pinned tags with digests, minimal base image selection, user creation for non-root execution, production-only dependencies, a health check that doesn't require extra binaries, and proper layer ordering.

Best Practices Summary

Here is a condensed checklist you can apply to any Dockerfile before it reaches production:

Measuring the Impact

To quantify the benefits of optimization, compare before and after metrics. A typical unoptimized Node.js image might weigh 900 MB and contain 200+ packages. After applying the techniques in this guide, the same application can ship as a 45 MB image with fewer than 10 packages. Here's how to measure:

# Pull both images and compare
docker pull myapp:unoptimized
docker pull myapp:optimized

# Size comparison
docker images myapp --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

# Package count comparison (Alpine-based)
docker run --rm --entrypoint apk myapp:optimized list --installed | wc -l
docker run --rm --entrypoint apk myapp:unoptimized list --installed | wc -l

# Vulnerability comparison
trivy image --severity HIGH,CRITICAL myapp:unoptimized
trivy image --severity HIGH,CRITICAL myapp:optimized

# Pull time comparison (simulate on a fresh node)
time docker pull myapp:unoptimized
time docker pull myapp:optimized

Conclusion

Docker image optimization is not a one-time task but an ongoing discipline. It begins with thoughtful Dockerfile authoring — choosing minimal base images, structuring layers for cache efficiency, and using multi-stage builds to shed build-time dependencies. It continues with measurement and iteration, using tools like Dive and Trivy to find bloat and vulnerabilities. And it extends into CI/CD pipelines, where digest pinning, vulnerability scanning, and size regression checks become automated gates.

The payoff is substantial: faster deployments, lower infrastructure costs, a dramatically reduced attack surface, and a development workflow that rewards good caching with sub-second rebuilds. Every megabyte you remove is a megabyte that doesn't need to be transferred, stored, scanned, or secured. In production, that compounds across hundreds of nodes and thousands of deployments. Start with the checklist above, apply the techniques to your next Dockerfile, and make optimization a habit rather than an afterthought.

🚀 Need a reliable AI agent for your project?

Deploy Hermes Agent in 10 minutes. Managed hosting, zero DevOps.

Get Started — $23.99/mo
← Back to all articles