<!--
  canonical-url: https://www.avonture.be/blog/docker-dive
  published:     2026-09-24
  This is a static plain-Markdown mirror generated at build time.
  Visit the canonical URL above for the fully rendered page, with images and interactive components.
-->

# Docker Dive — X-Ray Your Images and Kill the Waste

> Use dive to inspect every layer of a Docker image, spot wasted megabytes hidden by deleted files, and walk step by step from a 1 GB bloated image down to a tight, efficient build.

---
![Docker Dive — X-Ray Your Images and Kill the Waste](/img/v2/docker_dive.webp)

**TL;DR**

`dive` is an open-source terminal tool that renders every layer of a Docker image as an interactive file tree, highlighting exactly which files are wasted — present in one layer but deleted in a later one, yet still baked into the final image. This article walks through a deliberately broken Dockerfile, shows how dive exposes the waste, then fixes it in three incremental steps: cleaning apt caches in the same layer, collapsing multiple `RUN` statements into one, and switching to a multi-stage build that cuts the image by 80%. As a bonus, we push the idea to its logical extreme with `FROM scratch` — an image containing a single binary and nothing else.

Damn. I just ran `docker images` and there it was: `myapp:latest — 1.19 GB`. A Python web app with five dependencies, and somehow it ballooned to over a gigabyte. Something is deeply wrong with that Dockerfile.

The problem with Docker image bloat is that it's invisible until you look for it. Your containers start, your app runs, everything seems fine — and meanwhile you're shipping 400 MB of apt cache and build tools to production on every single deploy.

That's where [dive](https://github.com/wagoodman/dive) comes in. It's a terminal-based image inspector that lets you navigate the layers of any Docker image, see exactly what each `RUN`, `COPY`, and `ADD` instruction added or removed, and get a cold hard efficiency score at the bottom of the screen. Think of it as an X-ray machine for your images.

## What is Dive?

At its core, a Docker image is a stack of read-only layers. Every instruction in your Dockerfile that touches the filesystem creates a new layer. `apt-get install` — new layer. `pip install` — new layer. `COPY` — new layer.

Here's where the trap is: if you install a package in layer 3, then delete its cache in layer 5, the cache data is *still inside the image*. The deletion only marks the files as "opaque" in the upper layer — the bytes from layer 3 are still there, downloaded by every `docker pull`.

`dive` makes this visible. Left panel: the file tree of the selected layer. Right panel: the layer list with sizes. Bottom: your efficiency score and total wasted space.

> **Keyboard shortcuts inside dive:**
>
> Press `Tab` to switch between the layer list and the file tree. Use arrow keys to navigate layers. `Space` collapses/expands directories in the tree. Files shown in yellow are modified, in red are deleted — those deleted ones are your wasted bytes.

## Running Dive — No Installation Needed

You know me very well now; I like to containerize things. And `dive` has an official Docker image, so there's no reason to install anything on your host:

```bash
$ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock wagoodman/dive:latest myapp:latest
```

The `-v /var/run/docker.sock:/var/run/docker.sock` mount is required: it's how the `dive` container reaches back into your host Docker daemon to inspect images. If you're not comfortable with that — and it's a legitimate concern — refer to the [Docker-out-of-Docker article](/blog/docker-out-of-docker-dood) for the security context around socket mounting.

If you do prefer a local binary, `dive` is available on Linux, macOS, and Windows:

```bash
$ wget -q https://github.com/wagoodman/dive/releases/latest/download/dive_linux_amd64.tar.gz -O - | tar xz dive && sudo mv dive /usr/local/bin/
```

Either way, the usage is identical: `dive <image-name>`.

## The Patient: A Deliberately Terrible Dockerfile

Let's build something genuinely bad so we have something to analyze. Our app is a tiny Flask API — nothing fancy, just enough to pull in real dependencies:

**app.py**

```python
from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/")
def index():
    return "Hello from Docker!"

@app.route("/health")
def health():
    return jsonify({"status": "ok"})

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)
```

And the Dockerfile — written with zero regard for image size:

**Dockerfile.bad**

```bad
# syntax=docker/dockerfile:1
FROM ubuntu:24.04

RUN apt-get update
RUN apt-get install -y \
    curl \
    wget \
    git \
    python3 \
    python3-pip \
    build-essential \
    python3-dev \
    libssl-dev \
    pkg-config

RUN pip3 install flask requests numpy pandas scikit-learn --break-system-packages

RUN mkdir /app

COPY app.py /app/

WORKDIR /app

CMD ["python3", "app.py"]
```

Let's build it and see what we're dealing with:

```bash
$ docker build -t myapp:bad -f Dockerfile.bad .
[+] Building 142.3s (9/9) FINISHED
$ docker images myapp:bad
REPOSITORY   TAG    IMAGE ID       SIZE
myapp        bad    3f8c1a9e2b71   1.19GB
```

1.19 GB. For a five-file Flask app. Let's see exactly why.

## The Diagnosis: What Dive Reveals

```bash
$ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock wagoodman/dive:latest myapp:bad
```

What you'll see in the interactive TUI is something like this in the right panel (the layer list):

```plaintext
Cmp   Size  Command
     212 MB  FROM ubuntu:24.04
      38 MB  RUN apt-get update
     368 MB  RUN apt-get install -y curl wget git python3...
     184 MB  RUN pip3 install flask requests numpy pandas...
    0.0 B   RUN mkdir /app
    1.2 KB  COPY app.py /app/
```

The left panel shows the file tree for the selected layer. When you select the `apt-get update` layer, you'll see `/var/lib/apt/lists/` filled with hundreds of megabytes of package index files — and they're *still there* in every subsequent layer.

For a non-interactive, scriptable result, use the CI mode:

```bash
$ CI=true docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    wagoodman/dive:latest myapp:bad

  Using default CI config
Image Source: docker://myapp:bad
Fetching image... (this can take a while for large images)
Analyzing image...
  efficiency: 0.6341 (63.41%)
  wastedBytes: 438071296 bytes (438 MB)
  userWastedPercent: 36.59%
Result:FAIL [Total:3] [Passed:0] [Failed:3] [Warn:0] [Skipped:0]
```

**61.89% efficiency. 438 MB wasted.** That's brutal, and it's entirely self-inflicted.

> **What does 'wasted bytes' mean exactly?:**
>
> Dive counts a file as "wasted" when it exists in a lower layer but is deleted or overwritten in a higher layer. The original bytes from the lower layer are still physically present in the image — they just can't be seen in the running container. Every `docker pull` downloads them anyway.

## Fix #1 — Clean Up the apt Mess in the Same Layer

The first and most common mistake: separating `apt-get update` from the cleanup. The rule is simple — **anything you want to disappear must be deleted in the same `RUN` instruction**.

**Dockerfile.v2**

```v2
# syntax=docker/dockerfile:1
FROM ubuntu:24.04

RUN apt-get update && \
    apt-get install -y \
        curl \
        wget \
        git \
        python3 \
        python3-pip \
        build-essential \
        python3-dev \
        libssl-dev \
        pkg-config && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

RUN pip3 install flask requests numpy pandas scikit-learn --break-system-packages

RUN mkdir /app

COPY app.py /app/

WORKDIR /app

CMD ["python3", "app.py"]
```

The key change is the addition of `apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*` at the end of the apt install `RUN` block. This runs *inside the same layer*, so the cache files are never committed to the image.

```bash
$ docker build -t myapp:v2 -f Dockerfile.v2 .
$ docker images myapp:v2
REPOSITORY   TAG    IMAGE ID       SIZE
myapp        v2     7a4e0f1c9d83   712MB
```

712 MB instead of 1.19 GB. Nearly 500 MB gone. Let's confirm the improvement with dive:

```bash
$ CI=true docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    wagoodman/dive:latest myapp:v2

  Using default CI config
Image Source: docker://myapp:v2
Fetching image... (this can take a while for large images)
Analyzing image...
  efficiency: 0.9823 (98.23%)
  wastedBytes: 8192 bytes (8.2 kB)
  userWastedPercent: 1.77%
Result:PASS [Total:3] [Passed:3] [Failed:0] [Warn:0] [Skipped:0]
```

98.23% efficiency — a massive jump. But we're still at 712 MB for a tiny Flask app. There's more to fix.

## Fix #2 — Fewer Layers, Less Overhead

Look at the `Dockerfile.bad` layer list again. Each separate `RUN` statement creates its own layer. Even if a layer adds "only" a directory or a couple of kilobytes, every layer has metadata overhead — and more importantly, separating installation from cleanup makes it *impossible* to keep them in the same layer.

The solution: collapse related operations into a single `RUN` chain using `&&`:

**Dockerfile.v3**

```v3
# syntax=docker/dockerfile:1
FROM ubuntu:24.04

RUN apt-get update && \
    apt-get install -y \
        curl \
        wget \
        git \
        python3 \
        python3-pip \
        build-essential \
        python3-dev \
        libssl-dev \
        pkg-config && \
    pip3 install flask requests numpy pandas scikit-learn --break-system-packages && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && \
    find /usr -name "*.pyc" -delete 2>/dev/null; \
    find /usr -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null; true

RUN mkdir /app

COPY app.py /app/

WORKDIR /app

CMD ["python3", "app.py"]
```

Beyond the smaller layer count, notice the `find` commands at the end: they delete all `.pyc` compiled files and `__pycache__` directories that pip creates during installation. Those are pure waste in a production image.

```bash
$ docker build -t myapp:v3 -f Dockerfile.v3 .
$ docker images myapp
REPOSITORY   TAG    IMAGE ID       SIZE
myapp        bad    3f8c1a9e2b71   1.19GB
myapp        v2     7a4e0f1c9d83    712MB
myapp        v3     2b9d4e7f1c05    689MB
```

The gap between v2 and v3 is modest here — about 23 MB. The real value of collapsing `RUN` statements is clarity and correctness: you can no longer accidentally put cleanup in a different layer.

> **But 689 MB is still massive for a Flask app:**
>
> We still have `build-essential`, `python3-dev`, `libssl-dev`, `pkg-config`, `wget`, and `git` inside the production image. Those are build-time tools — they were needed to compile some pip packages, but they have no business being in the image that runs in production. This is where the single-stage approach hits its ceiling.

## Fix #3 — The Multi-stage Build

The core idea of a multi-stage build is simple: use one `FROM` to build, use another `FROM` to run. The builder stage can be as fat as it wants — tools, caches, compilers — because only the final stage gets shipped.

**Dockerfile.multistage**

```multistage
# syntax=docker/dockerfile:1

FROM python:3.12 AS builder

WORKDIR /build

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt --target ./packages

FROM python:3.12-slim AS production

WORKDIR /app

COPY --from=builder /build/packages ./packages

ENV PYTHONPATH=/app/packages

COPY app.py .

CMD ["python3", "app.py"]
```

What's happening here:

1. `FROM python:3.12 AS builder` — full Python image, used only to install packages
2. `pip install --target ./packages` — installs everything into a local directory (not system-wide)
3. `FROM python:3.12-slim AS production` — the slim base image, about 130 MB
4. `COPY --from=builder /build/packages ./packages` — only the installed packages cross the boundary; no build tools, no pip cache, no apt lists

```bash
$ docker build -t myapp:multistage -f Dockerfile.multistage .
$ docker images myapp
REPOSITORY   TAG          IMAGE ID       SIZE
myapp        bad          3f8c1a9e2b71   1.19GB
myapp        v2           7a4e0f1c9d83    712MB
myapp        v3           2b9d4e7f1c05    689MB
myapp        multistage   9c3a1f8e4b22    247MB
```

247 MB — an 80% reduction from our starting point. And the dive score:

```bash
$ CI=true docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    wagoodman/dive:latest myapp:multistage

  Using default CI config
Image Source: docker://myapp:multistage
Fetching image... (this can take a while for large images)
Analyzing image...
  efficiency: 0.9971 (99.71%)
  wastedBytes: 4096 bytes (4.1 kB)
  userWastedPercent: 0.29%
Result:PASS [Total:3] [Passed:3] [Failed:0] [Warn:0] [Skipped:0]
```

99.71% efficiency. The remaining 4 KB of "wasted" bytes are background noise — Docker layer metadata that can't be avoided.

> **Pick the right slim base:**
>
> `python:3.12-slim` is the sweet spot for most Python apps. `python:3.12-alpine` is even smaller (about 20 MB) but uses `musl libc` instead of `glibc`, which can cause compatibility issues with binary wheels like `numpy` or `pandas`. Test before committing to Alpine for a data-heavy stack.

Multi-stage builds are also the right approach for compiled languages. If you're building a Go, Rust, or C app, the builder stage contains the entire compiler toolchain, and only the final binary ends up in the production stage. Which brings us to the bonus section.

## Bonus — FROM scratch: The Absolute Minimum

`FROM scratch` is a special Docker keyword — it's not an image name, it's a signal to the Docker builder that the new image should start completely empty. No shell, no package manager, no libc, no anything. Just the files you explicitly `COPY` into it.

This only works if your application is a self-contained binary with zero external dependencies. Statically compiled Go is the poster child:

**Dockerfile.scratch**

```scratch
# syntax=docker/dockerfile:1

FROM golang:1.22-alpine AS builder

WORKDIR /build

COPY main.go .

RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-w -s' -o server .

FROM scratch

COPY --from=builder /build/server /server

EXPOSE 8080

ENTRYPOINT ["/server"]
```

**main.go**

```go
package main

import (
	"fmt"
	"log"
	"net/http"
)

func main() {
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "Hello from a minimal Docker image!")
	})

	log.Println("Starting server on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}
```

The `-ldflags '-w -s'` flags strip debug information and the symbol table, shaving a few more MB off the binary.

```bash
$ docker build -t myserver:scratch -f Dockerfile.scratch .
$ docker images myserver:scratch
REPOSITORY   TAG       IMAGE ID       SIZE
myserver     scratch   1a2b3c4d5e6f    6.88MB
```

6.88 MB. Less than 7 MB for a production HTTP server. And dive?

```bash
$ CI=true docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    wagoodman/dive:latest myserver:scratch

  Using default CI config
Image Source: docker://myserver:scratch
Fetching image... (this can take a while for large images)
Analyzing image...
  efficiency: 1.0000 (100.00%)
  wastedBytes: 0 bytes (0 B)
  userWastedPercent: 0.00%
Result:PASS [Total:3] [Passed:3] [Failed:0] [Warn:0] [Skipped:0]
```

100.00% efficiency. 0 bytes wasted. There is literally nowhere left to improve.

> **FROM scratch isn't always practical:**
>
> A scratch image has no shell at all — `docker exec mycontainer sh` will fail. No shell means no shell scripts in your entrypoint, no `ping`, no `curl` for health checks from inside the container. For debugging, consider `gcr.io/distroless/static` instead: it's nearly as small as scratch but includes a handful of POSIX tools and is maintained by Google for security patches.

## Dive as a CI Quality Gate

Manually running dive is useful during development, but the real power is in the `--ci` mode — it reads a configuration file and fails with a non-zero exit code if your image doesn't meet the thresholds. Plug this directly into your pipeline.

Create a `.dive-ci.yaml` at the root of your project:

**.dive-ci.yaml**

```yaml
rules:
  lowestEfficiency: 0.95
  highestWastedBytes: "20mb"
  highestUserWastedPercent: 0.05
```

Then add a step in your CI pipeline:

```bash
$ DIVE_CONFIG=.dive-ci.yaml CI=true docker run --rm 
-v /var/run/docker.sock:/var/run/docker.sock 
-v $(pwd)/.dive-ci.yaml:/.dive-ci.yaml 
-e DIVE_CONFIG=/.dive-ci.yaml 
wagoodman/dive:latest myapp:latest
```

If the image efficiency drops below 95% or wasted bytes exceed 20 MB, the step fails and the deploy never happens. So cool no?

> **What thresholds make sense?:**
>
> `lowestEfficiency: 0.95` and `highestWastedBytes: "20mb"` are sensible defaults for a first pass. Adjust `highestWastedBytes` upward if your image legitimately includes large static assets (fonts, models, datasets) that can't be cleanly separated.

## Claude Code — Automate the Entire Loop

Everything we've done manually — run dive, read the JSON, spot the wasted layers, decide what to fix, edit the Dockerfile, rebuild, re-run — is a repeatable loop. If you use [Claude Code](https://claude.ai/code), you can drive the whole thing with a single slash command:

```text
/docker-dive-optimization
```

It auto-discovers the project's main Dockerfile (or accepts a path or image tag as argument), builds the image, runs dive in JSON mode, and classifies every finding into three buckets — mapping directly to the patterns we've been applying by hand in this article.

**Bucket A — fix now**: Mechanical waste that's unambiguously wrong. `apt-get clean` sitting in a separate `RUN` from the install, `--no-cache` missing from an `apk add`, a cache directory not cleaned in the same layer that created it. Claude applies the Dockerfile edit, rebuilds, and re-runs dive to verify the gain before reporting success.

**Bucket B — propose and wait**: Findings where the right answer requires a judgment call. Switching from `python:3.12` to `python:3.12-slim` in a production stage. Introducing a multi-stage build where there isn't one. Replacing a 300 MB runtime that's only there for a single CLI call with a standalone binary. Claude presents the layer evidence and the trade-off, then waits for your decision before touching anything.

**Bucket C — TODOs**: Everything that needs research before it can be touched. Filed as numbered items in `.todos/` so they don't get lost between sessions.

> **Target any image or Dockerfile:**
>
> The command defaults to the project's own Dockerfile, but it accepts a path or an image tag directly:
>
> ```text
> /docker-dive-optimization myapp:latest
> /docker-dive-optimization ./services/api/Dockerfile
> ```
>
> You can copy the command file into any project's `.claude/commands/` directory — it auto-discovers whether to use `docker compose build` or a plain `docker build`, so no project-specific wiring is needed.

The three-bucket split mirrors the judgment calls in this article. Cleaning apt cache in the same layer is Bucket A — no discussion needed, just merge and verify. Switching to a multi-stage build is Bucket B — real trade-offs to review first. Replacing a niche binary you've never audited is Bucket C — research before touching. Same analysis we did manually, automated.

To prove the point: I ran `/docker-dive-optimization` on the very blog you're reading right now. The devcontainer image had ballooned to **2.5 GB**, scored 89.95% efficiency, and carried 433 MB of wasted bytes — mostly inherited from a heavy `mcr.microsoft.com/devcontainers/javascript-node:20-bookworm` base that silently baked in oh-my-zsh, subversion, and a full C/C++ build toolchain nobody had asked for. Bucket A caught a redundant `chown -R` that forced Docker's overlay FS to copy 1 410 files into a useless 21 MB layer. Bucket B flagged the base image and 996 MB of `node_modules` baked into every build.

![dive result before and after optimization on this blog](./images/final_result.png)

**From 2.5 GB down to 735 MB — a 70% reduction, efficiency up from 89.95% to 98.75%.** The base image swap from the devcontainer-specific image to `node:20-bookworm-slim` alone saved over a gigabyte. Moving `node_modules` to a named Docker volume at runtime recovered another 996 MB. The whole session — including the rebuild and the dive re-run to verify — took under fifteen minutes.

## Putting It All Together

Here's the progression we went through:

**The four-step journey**

* **Start (Dockerfile.bad) — 1.19 GB, 61% efficiency**: Separate `RUN apt-get update`, no cache cleanup, build tools in the final image.

* **v2 — 712 MB, 98% efficiency**: Clean `apt` cache and lists in the same `RUN` instruction that installs them.

* **v3 — 689 MB, 98% efficiency**: Collapse all installation steps into one `RUN` chain, delete `.pyc` files.

* **Multi-stage — 247 MB, 99.7% efficiency**: Use a separate builder stage; only the installed packages cross into the slim production image.

* **Bonus (FROM scratch) — 6.88 MB, 100% efficiency**: Statically compiled binary, no base image at all.

## Conclusion

There's a version of this story where you ship a 1.2 GB image to production because it works — and you never look back. I've been there. The app runs, the team ships, nobody complains. Until you look at your registry storage bill, or your cold-start time on a serverless platform, or the pull time on a CI runner with a fresh cache.

`dive` makes the invisible visible. Once you see 438 MB of wasted bytes labeled in red, you can't unsee it. The fixes aren't exotic — clean up in the same layer, combine your `RUN` statements, use multi-stage builds. These are things every Docker practitioner should know by heart, and now you have a tool that will tell you immediately if you've forgotten one.

For more context on writing production-grade Dockerfiles, [One Docker Image for Production and Devcontainers](/blog/docker-prod-devcontainer) covers the single-source-of-truth approach where one Dockerfile handles both environments cleanly. And if you're looking for another terminal-first Docker tool, there's a companion article on [lazydocker](/blog/lazydocker) — a full TUI dashboard for managing your containers and logs without leaving the terminal.
