---
title: "optimize dockerfile"
description: "Optimize an existing Dockerfile for smaller images, faster builds, and better security."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/optimize-dockerfile
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:31:35.384Z
license: CC-BY-4.0
attribution: "optimize dockerfile — Claudary (https://claudary.paisolsolutions.com/skills/optimize-dockerfile)"
---

# optimize dockerfile
Optimize an existing Dockerfile for smaller images, faster builds, and better security.

## Overview

Optimize an existing Dockerfile for smaller images, faster builds, and better security.

## Steps

1. Read the existing Dockerfile and analyze each instruction.
2. Check for size optimization opportunities:
   - Use Alpine or distroless base images where possible.
   - Combine RUN commands to reduce layers.
   - Remove package manager caches in the same layer as installs.
   - Use multi-stage builds to exclude build tools from the final image.
   - Copy only necessary files, not the entire context.
3. Check for build cache optimization:
   - Order instructions from least to most frequently changing.
   - Copy dependency files before source code.
   - Use `--mount=type=cache` for package manager caches.
4. Check for security best practices:
   - Use specific version tags for base images.
   - Run as non-root user: `USER <non-root>`.
   - Set `HEALTHCHECK` instruction.
   - Do not store secrets in environment variables or build args.
   - Minimize installed packages to reduce attack surface.
5. Apply optimizations and compare before/after image sizes.
6. Verify the optimized image still runs correctly.

## Format

```
Dockerfile Optimization: <path>

Before: <size>MB, <layers> layers
After: <size>MB, <layers> layers
Reduction: <percent>%

Changes:
  1. Switched base from node:20 to node:20-alpine (-600MB)
  2. Combined 5 RUN commands into 2 (-3 layers)
  3. Added multi-stage build, excluded devDependencies (-200MB)
  4. Added non-root USER instruction (security)

Verification: container starts and passes health check
```

## Rules

- Always test the optimized image before recommending changes.
- Do not sacrifice build reliability for marginal size gains.
- Preserve build cache efficiency; do not combine steps that change independently.
- Keep security fixes separate from optimization changes for clear review.
- Document why each base image was chosen.

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/optimize-dockerfile) · https://claudary.paisolsolutions.com