Skip to content
Get packs

Guide · Open source

How to use dive: explore Docker image layers and find wasted space

Updated · written with AI from the project's own documentation and checked against our catalogue data

Dive is an open-source command-line tool that opens a Docker image and lets you explore its contents layer by layer. It shows which files each layer adds, changes or removes, and estimates how much of the image is wasted space. This guide walks through installing it, analyzing an image, reading the results and using its CI mode, so you can work out why an image is larger than expected.

divewagoodman/dive · ★ 54.7k · MIT

Quick start

  1. 1Install dive. Install dive with your package manager, for example brew install dive on Mac. Make sure Docker or Podman is available.
  2. 2Pick an image. Choose the image tag, ID or digest you want to inspect, such as nginx:latest.
  3. 3Run the analysis. Run dive with the image name to open the layer view.
  4. 4Inspect layers. Select layers on the left and browse the file tree on the right to see which files each layer adds, changes or removes.
  5. 5Check wasted space. Read the efficiency score and wasted space in the lower left pane and note which layers contribute most.
  6. 6Add a CI rule. Create a .dive-ci file with thresholds and run CI=true dive <your-image> to get a pass or fail result.

Install dive on your system

Dive is installed with your system's package manager. The source lists these commands: Homebrew on Mac, winget on Windows and pacman on Arch Linux. Other options in the README include Chocolatey, scoop, MacPorts, Nix, and Debian or RPM packages from the releases page.

The only prerequisite is Docker or Podman, depending on which image source you use.

  • Mac with Homebrew: brew install dive
  • Windows with winget: winget install --id wagoodman.dive
  • Arch Linux with pacman: pacman -S dive
brew install dive

Analyze a Docker image with dive

Run dive followed by an image tag, ID or digest. Dive opens the image and shows its layers on the left and the file tree on the right. Selecting a layer shows the contents of that layer combined with all the layers before it.

If you want to build an image and analyze it in one step, use dive build with the same arguments you would give docker build.

  • Select a layer on the left to see the file tree for that layer combined with the previous layers.
  • Use the arrow keys to move through the file tree and expand directories.
  • Files marked as changed, modified, added or removed are indicated in the tree.
dive <your-image-tag> dive build -t <some-tag> .

Choose where dive reads the image from

By default dive reads images from the Docker engine. The --source option lets you pick another source, either as a flag or as a prefix in the image reference.

  • docker: Docker engine (the default)
  • docker-archive: a Docker tar archive on disk
  • podman: Podman engine (Linux only)
dive <your-image> --source <source> dive <source>://<your-image>

Read the efficiency score and wasted space

The lower left pane shows basic layer information and an efficiency estimate. The estimate guesses how much wasted space the image contains, which can come from files duplicated across layers, files moved between layers, or files not fully removed. It is shown as a percentage score and as a total amount of wasted file space.

The README labels this metric experimental, so treat it as a guide for finding candidates to fix rather than an exact measurement.

Run dive in CI to check image efficiency

Setting CI=true skips the interactive interface and analyzes the image, returning a pass or fail result through the return code. Rules go in a .dive-ci file at the root of your repository. You can point to a different file with the --ci-config option.

The three supported rules are lowestEfficiency (a ratio from 0 to 1), highestWastedBytes (such as 20MB) and highestUserWastedPercent (a ratio from 0 to 1, where the base image layer is not counted in the total).

  • Set CI=true in the environment when running any valid dive command.
  • Add a .dive-ci file at the repository root with your thresholds.
CI=true dive <your-image> rules: lowestEfficiency: 0.95 highestWastedBytes: 20MB highestUserWastedPercent: 0.20

Use the keyboard to move around

Dive is driven from the keyboard. Tab switches between the layer and file tree views, and Ctrl + F filters files. Arrow keys or K and J move one line, and PageUp/PageDown or U and D scroll a page. Ctrl + C or Q exits.

  • Tab: switch between the layer and filetree views
  • Ctrl + F: filter files, ESC closes the filter
  • Q or Ctrl + C: exit

What people use it for

  • Finding out why a Docker image is larger than expected by browsing its layers.
  • Locating duplicated or leftover files that add wasted space to an image.
  • Checking image size before deployment to speed up pulls.
  • Adding a CI step that fails a build when efficiency drops below a threshold.
  • Viewing a Docker image's layer structure visually in the terminal.

Frequently asked questions

Is dive free to use?

Dive is open source and released under the MIT licence, according to its repository. The source does not list any paid tier.

What do I need to run dive?

You need Docker or Podman, depending on the image source you use. Dive only inspects Docker and OCI images.

How do I install dive on Mac?

If you use Homebrew, run brew install dive. The README also lists MacPorts and a downloadable Darwin build from the releases page.

Is dive stable enough for production?

The README says dive is beta quality, so it is not presented as a fully stable production-grade tool. Feedback and bug reports are welcome through issues.

How accurate is the efficiency score?

The README calls the efficiency metric experimental. It guesses wasted space, so use it to find areas to investigate rather than as an exact figure.

What are alternatives to dive?

The source lists docker-slim, container-diff and skopeo as comparable projects. The source does not compare them in detail, so check each one's documentation for your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Dive suits developers and teams who want to see inside a Docker image layer by layer, trim its size, or add a basic efficiency check to CI. Skip it if you need a fully stable tool or an exact efficiency score, or if you do not use Docker or OCI images.

Install options & downloads