Generate Multi-Stage Dockerfiles (2026)

Docker multi-stage builds are one of the most effective ways to reduce image size and improve build performance. Claude Code can help you generate optimized, production-ready Dockerfiles that follow industry best practices. this guide covers how to use Claude Code to create efficient multi-stage Dockerfile configurations for various application types.

Why Multi-Stage Builds Matter

Traditional Dockerfiles often result in bloated images that include build dependencies, development tools, and temporary files that aren’t needed at runtime. A single-stage build might produce images of 1GB or more, even for simple applications.

Multi-stage builds solve this problem by allowing you to use multiple FROM statements in a single Dockerfile. Early stages can include build tools and dependencies, while final stages contain only what’s necessary to run your application. This approach offers several critical benefits:

Image Size Reduction: Eliminating build dependencies from final images can reduce size by 50-90%. Smaller images mean faster deployments, reduced storage costs, and quicker container startup times.

Security Improvements: By removing development tools like compilers, package managers, and debugging utilities from production images, you reduce the attack surface and potential security vulnerabilities.

Build Performance: Multi-stage builds with proper layer caching can dramatically speed up rebuild times. Only layers that change need to be rebuilt, while unchanged layers are reused from cache.

Maintainability: Clear stage separation makes Dockerfiles easier to understand and modify. Each stage has a specific purpose, making the file self-documenting.

Understanding the Multi-Stage Pattern

The basic multi-stage pattern uses multiple FROM statements, with each stage serving a specific purpose. Here’s the fundamental structure:

Stage 1: Builder stage - includes all build tools and dependencies
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
Stage 2: Runtime stage - only includes necessary runtime dependencies
FROM node:20-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json ./
EXPOSE 3000
CMD ["node", "dist/index.js"]

In this example, the builder stage compiles the application and installs all dependencies. The runtime stage copies only the compiled output and essential node_modules, resulting in a significantly smaller final image. Build tools like the TypeScript compiler are never included in the final image.

Layer Caching and Optimization Strategies

Effective use of Docker layer caching is essential for fast builds. Docker caches layers based on the Dockerfile instruction and file contents. If nothing has changed, Docker reuses the cached layer instead of rebuilding it.

Ordering Matters: Place instructions that change frequently toward the end of your Dockerfile. If you modify your source code, you don’t want to invalidate the cache for dependency installation. Copy package files first, install dependencies, then copy source code:

FROM node:20-alpine AS builder
WORKDIR /app
Copy dependency files first (less likely to change)
COPY package*.json ./
RUN npm ci
Copy source code last (changes most frequently)
COPY . .
RUN npm run build

Use .dockerignore: Create a .dockerignore file in your project root to exclude files that shouldn’t be copied into the image. This prevents unnecessary cache invalidation:

node_modules
npm-debug.log
.git
.gitignore
.env
.env.local
.DS_Store
dist
coverage

When you exclude files with .dockerignore, Docker doesn’t consider them when calculating checksums for caching. This means adding a new .log file or updating .gitignore won’t invalidate your dependency installation cache.

Multi-stage Advantages for Caching: Each stage has its own cache context. You can have a build stage that takes 10 minutes to compile, but if you only change the final COPY command in the runtime stage, the builder cache remains valid and your rebuild completes in seconds.

Node.js Multi-Stage Build Example

Here’s a production-ready multi-stage Dockerfile for a Node.js application with development and production dependencies:

Stage 1: Dependency installer - installs all dependencies
FROM node:20-alpine AS dependencies
WORKDIR /app
COPY package*.json ./
RUN npm ci
Stage 2: Builder - compiles TypeScript and builds the application
FROM dependencies AS builder
COPY . .
RUN npm run build
Stage 3: Production dependencies only
FROM node:20-alpine AS prod-dependencies
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
Stage 4: Runtime - minimal production image
FROM node:20-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/dist ./dist
COPY --from=prod-dependencies /app/node_modules ./node_modules
COPY package.json ./
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
 CMD node -e "require('http').get('http://localhost:3000/health', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})"
CMD ["node", "dist/index.js"]

This pattern separates dependency installation from source compilation and creates a prod-dependencies stage to exclude dev dependencies from the final image. The result is a lean, production-ready container.

Python Multi-Stage Build Example

Python applications benefit equally from multi-stage builds. Here’s a pattern for a Python web application:

Stage 1: Builder - installs dependencies and builds wheels
FROM python:3.11-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt
Stage 2: Runtime - minimal production image
FROM python:3.11-slim
WORKDIR /app
ENV PYTHONUNBUFFERED=1
COPY --from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
EXPOSE 5000
CMD ["python", "-m", "flask", "run", "--host=0.0.0.0"]

This approach installs dependencies into /root/.local during the build stage, then copies only the user-installed packages to the runtime stage. The final image includes only Python runtime and your application code, not pip, setuptools, or other build tools.

How Claude Code Accelerates Dockerfile Generation

Claude Code excels at understanding your project structure and requirements, then generating tailored multi-stage Dockerfiles. When you describe your application’s dependencies, build process, and runtime needs, Claude Code produces Dockerfiles that:

  • Follow Docker best practices and modern patterns
  • Implement proper layer caching strategies
  • Use appropriate base images for your technology stack
  • Include health checks and proper signal handling
  • Add helpful comments explaining each stage’s purpose
  • Consider security and minimal attack surface

You can ask Claude Code to generate a Dockerfile, then iteratively refine it. Need to add a build argument? Modify the health check? Include a specific runtime flag? Claude Code updates the configuration instantly while maintaining the multi-stage structure and caching efficiency.

Claude Code also helps you understand why specific choices were made in a generated Dockerfile, making it easier to maintain and modify the configuration as your application evolves.

Best Practices Summary

When generating or reviewing multi-stage Dockerfiles with Claude Code, remember these key principles:

  • Use specific base image tags (never just node or python)
  • Place frequently-changing instructions late in each stage
  • Use .dockerignore to prevent cache invalidation
  • Install production dependencies in a separate stage from build dependencies
  • Keep runtime stages minimal and security-focused
  • Include health checks for long-running services
  • Use appropriate signal handlers for graceful shutdowns
This took me 3 hours to figure out. I put it in a CLAUDE.md so I'd never figure it out again. Now Claude gets it right on the first try, every project. 16 framework templates. Next.js, FastAPI, Laravel, Rails, Go, Rust, Terraform, and 9 more. Each one 300+ lines of "here's exactly how this stack works." Copy into your project. Done. **[See the templates →](https://zovo.one/lifetime?utm_source=ccg&utm_medium=cta-deploy&utm_campaign=claude-code-dockerfile-generation-multi-stage-build-guide)** $99 once. Yours forever. I keep adding templates monthly.

Related Reading

Built by theluckystrike. More at zovo.one

Find the right skill → Browse 155+ skills in our Skill Finder.

See Also

Try it: Paste your error into our Error Diagnostic for an instant fix.