dive: reading a container image layer by layer, and what its wasted-space score can and cannot tell you
GitHub describes it as A tool for exploring each layer in a docker image. The repository metadata lists Go as its primary language. The metadata lists the MIT license. This article stays within the project description and details documented in the GitHub repository README.
At a glance
- What is it?
- dive is a Go terminal tool that opens a Docker or OCI image, shows each layer's file changes, and estimates wasted space. This guide covers its layer view, its CI mode, the nine image sources it can read from, and the install and release caveats that matter before you depend on it.
- Who is it for?
- dive suits anyone trying to shrink a Docker or OCI image, because it shows exactly which layer added, changed or removed each file and flags duplicated or leftover data. It is a weaker fit as a strict CI gate, since the efficiency metric is labeled experimental and the tool calls itself beta quality.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- wagoodman/dive54,726 ★ · +273
| Repository | 2026-08-13 | 2026-11-15 |
|---|---|---|
| wagoodman/dive | 54.5k | 54.7k |
273 Stars in the last 94 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Each selected layer shows the merged file tree up to that point
dive opens an image in a terminal interface split into panes. Selecting a layer on the left shows, on the right, the contents of that layer combined with every layer before it, and the arrow keys walk the full file tree. Files that were added, modified or removed are marked in the tree. You can switch between seeing only the changes a single layer introduced and the aggregated changes up to that layer, which is the view that answers the question of where a large file first appeared.
The basic invocation takes a tag, an image ID or a digest:
dive <your-image-tag>If you would rather not install a binary, the project publishes a container image and suggests an alias that mounts the Docker socket:
alias dive="docker run -ti --rm -v /var/run/docker.sock:/var/run/docker.sock docker.io/wagoodman/dive"
dive <your-image-tag>
# for example
dive nginx:latestThat image is built on alpine:3.21 with a static Docker CLI copied in, and the Dockerfile notes it was kept off scratch on purpose so users can exec into it.
The efficiency score is an experimental guess, not a measurement
The lower left pane shows basic layer information and an image efficiency estimate. dive reports two numbers: a percentage score and the total wasted file space. The waste it looks for comes from three patterns: the same file duplicated across layers, files moved between layers, and files that were not fully removed, such as something deleted in a later layer that still ships in an earlier one.
The project itself calls this metric experimental and says it will guess at wasted space. That wording matters for how you use it. The number is a good pointer toward layers worth inspecting by hand, but a change in score between two builds does not by itself prove the image got better or worse in a way your users will notice. Treat the wasted-bytes figure as a list of suspects and confirm each one in the file tree before restructuring a Dockerfile around it. The pane gives you the score; the layer view gives you the evidence.
CI mode turns the score into a pass or fail result
Setting CI=true in the environment of any valid dive command skips the interface and produces a pass or fail result based on image efficiency and wasted space:
CI=true dive <your-image>The repository's own Makefile shows the flag form used in its Windows test target, with an explicit source, a saved test image and a rules file: dive.exe --source docker-archive .data/test-docker-image.tar --ci --ci-config .data/.dive-ci. So the thresholds live in a config file you pass with --ci-config, and a tarball produced by docker save can be checked without any running engine.
The consequence of the experimental metric shows up here. A pipeline that fails builds on the efficiency score inherits whatever guesses the metric makes, and dive describes itself as beta quality. Start with thresholds loose enough that a failure always reflects real waste you can find in the tree, and tighten them only after reviewing a few runs. For a machine-readable record instead of a verdict, --json <path> skips the interface and writes the full analysis to a file, where each layer's id is its diff ID, the same value as digestId.
dive build wraps docker build, and on macOS only through Docker
To build an image and open it immediately, swap docker build for dive build with the same arguments:
dive build -t <some-tag> .On macOS the build path is supported only with the Docker container engine, run through the dive container image with the working directory and your dive config mounted in:
docker run --rm -it \
-v /var/run/docker.sock:/var/run/docker.sock \
-v "$(pwd)":"$(pwd)" \
-w "$(pwd)" \
-v "$HOME/.dive.yaml":"$HOME/.dive.yaml" \
docker.io/wagoodman/dive:latest build -t <some-tag> .That command also shows where per-user settings live: a .dive.yaml file in your home directory. If you use Podman or another engine on a Mac, dive build is not the route; build with your engine first and then point dive at the result with --source. The container approach also means the dive version you run is whatever docker.io/wagoodman/dive:latest resolves to, not a version you pinned.
Nine image sources, and a colon rule that decides how names parse
The --source option picks where dive reads the image from, or you can prefix the image with a scheme:
dive <your-image> --source <source>dive <source>://<your-image>The default, docker, talks to the Docker engine, pulls missing images through the Docker API with credentials from your Docker config, and honors DOCKER_HOST, DOCKER_CONTEXT and the current context. podman reads the local store directly on Linux, so no socket is needed and a short name such as myapp also finds localhost/myapp, falling back to the podman socket; on macOS it finds the running podman machine's API socket through podman machine inspect, CONTAINER_HOST can override it, and ssh connections are refused. docker-archive (alias docker-tar) reads a docker save tarball or an OCI archive, oci-archive and oci-dir read OCI layouts as a tarball or a directory, registry pulls without any engine, and containerd uses CONTAINERD_NAMESPACE to choose a namespace.
File-based sources also accept the source:path form other anchore tools use, as in dive oci-dir:./layout. For every other source a single colon is read as name and tag, so dive docker:dind analyzes the docker:dind image rather than selecting the docker source.
auto can fall through to Docker Hub, and some sources refuse to connect
The auto source checks files on disk first, then docker, podman, containerd and containers-storage, and finally pulls from a registry. dive reports which source it picked, and that report is worth reading: an image no local engine has will quietly come from a registry, which means Docker Hub for a short name. A typo in a local tag can therefore turn into a public pull of an unrelated image with a similar name. auto works only with --source, not as a scheme prefix.
Several sources deliberately refuse cases you might expect to work. The registry source rejects registries on private IP addresses, because they would be reached over plain http, so an internal registry on a LAN address cannot be read that way. Podman over ssh is refused. containers-storage, the local podman and buildah store, is Linux only and is compiled in only with the containers_image_openpgp build tag; the Linux release builds and the Docker image include it, and without it the source reports that it is unavailable. For multi-platform images, --platform picks the variant, for example --platform linux/arm64, while a docker save tarball holds one platform and dive reports a mismatch.
Snap packaging can break an apt-installed Docker daemon
Linux packages come from the GitHub releases page. On Ubuntu and Debian, the deb route reads the latest tag from the GitHub API and downloads the amd64 package:
DIVE_VERSION=$(curl -sL "https://api.github.com/repos/wagoodman/dive/releases/latest" | grep '"tag_name":' | sed -E 's/.*"v([^"]+)".*/\1/')
curl -fOL "https://github.com/wagoodman/dive/releases/download/v${DIVE_VERSION}/dive_${DIVE_VERSION}_linux_amd64.deb"
sudo apt install ./dive_${DIVE_VERSION}_linux_amd64.debRHEL and CentOS use the same version lookup with an rpm and rpm -i. Arch Linux has dive in the extra repository through pacman -S dive. On a Mac, brew install dive or sudo port install dive both work, or you can download the Darwin build from the releases page.
The snap route installs Docker from snap as well and connects two interfaces:
sudo snap install docker
sudo snap install dive
sudo snap connect dive:docker-executables docker:docker-executables
sudo snap connect dive:docker-daemon docker:docker-daemonThe project marks this method as not recommended if Docker was installed with apt-get, since it can break the existing Docker daemon, and links issue 546. On a machine that already runs Docker from apt, use the deb instead.
The last tagged release trails the main branch by over a year and a half
The newest GitHub release is v0.13.1 from March 29, 2025, following v0.13.0 on March 21, 2025 and v0.12.0 on February 2, 2024. The repository itself is not archived and saw its last push on November 2, 2026. Package managers and the deb and rpm commands install tagged releases, so the binary you get from them is v0.13.1 unless a newer tag appears. Options and sources you read about on the main branch need checking against dive --help on the installed binary before you write scripts around them.
Building from main is the alternative. go.mod declares go 1.26.8, and the module builds on anchore's stereoscope, go-containerregistry, the Docker CLI and moby client libraries, and bubbletea and gocui for the interface. To include containers-storage support, build with the tag the project gives:
go build -tags containers_image_openpgp,exclude_graphdriver_btrfs ./cmd/diveFor development, the Makefile is only a shim: it downloads binny with a curl pipe to sh, uses binny to install the task runner into .tool, and forwards make targets to Taskfile.yaml.
Editorial conclusion
dive suits anyone trying to shrink a Docker or OCI image, because it shows exactly which layer added, changed or removed each file and flags duplicated or leftover data. It is a weaker fit as a strict CI gate, since the efficiency metric is labeled experimental and the tool calls itself beta quality. Before relying on a specific source such as containerd or podman, check that your installed binary supports it, because the newest tagged release dates from March 29, 2025 while the main branch kept changing into November 2026.
Frequently asked questions
What does dive show about a Docker image?
dive shows each layer of a Docker or OCI image, the file tree combined up to the selected layer, and which files were added, modified or removed. It also estimates wasted space as a percentage score and a total in bytes.
Can dive run in a CI pipeline?
Yes. Setting CI=true when invoking any dive command skips the interface and returns a pass or fail result based on image efficiency and wasted space, and --ci-config points to a rules file.
Can dive analyze an image without a running Docker daemon?
Yes. The docker-archive, oci-archive and oci-dir sources read images from files on disk, and the registry source pulls without any container engine, though it refuses registries on private IP addresses.
How do I install dive on Ubuntu?
Download the dive_<version>_linux_amd64.deb from the GitHub releases page and install it with apt. A snap package exists, but it is not recommended if Docker was installed with apt-get because it can break the existing Docker daemon.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/wagoodman-dive)Star history chart for your README
[](https://hysenlabs.com/projects/wagoodman-dive)Was this useful?