dive

dive is a command-line tool for exploring a Docker/OCI image, inspecting each layer's contents, and discovering ways to reduce image size. It is written in Go and released under the MIT license. ## Core usage Analyze an existing image by tag, ID, or digest: ```bash dive <your-image-tag> ``` It can also be run directly through Docker by mounting the Docker socket: ```bash alias dive="docker run -ti --rm -v /var/run/docker.sock:/var/run/docker.sock docker.io/wagoodman/dive" dive nginx:latest ``` Images can be built and then immediately analyzed in one step: ```bash dive build -t <some-tag> . ``` ## Basic features - **Layer-by-layer image contents**: Select a layer on the left to view the combined contents of that layer and all previous layers on the right. The file tree can be navigated with arrow keys. - **Layer change indicators**: Files that were added, modified, or removed are highlighted in the file tree. The view can be switched between changes for a specific layer or aggregated changes up to the selected layer. - **Image efficiency estimate**: The lower-left pane shows basic layer information and an experimental metric estimating wasted space, such as duplicated files across layers, moved files, or incompletely removed files. Both a percentage score and total wasted file space are provided. - **Quick build/analysis cycles**: Replace `docker build` with `dive build` to analyze the image immediately after building. - **CI integration**: With `CI=true` set in the environment, the UI is skipped and the image is analyzed with a pass/fail result based on rules. - **Multiple image sources**: The `--source` option selects where to fetch the image from. Supported sources include `docker` (default), `docker-archive` (a Docker tar archive from disk), and `podman` (Linux only). ## CI integration Running dive with `CI=true` bypasses the interactive UI and returns a pass/fail indication through the exit code. A `.dive-ci` file at the root of the repository can define rules: ```yaml rules: # Fail if efficiency is below X%, expressed as a ratio between 0-1. lowestEfficiency: 0.95 # Fail if wasted space is at least X or larger, expressed in B, KB, MB, GB. highestWastedBytes: 20MB # Fail if wasted space makes up X% or more of the image, expressed as a ratio between 0-1. # The base image layer is not included in the total image size. highestUserWastedPercent: 0.20 ``` The CI config path can be overridden with `--ci-config`. ## Installation Several installation methods are documented: - **Ubuntu/Debian**: download the `.deb` release and install with `apt`. - **Snap**: `snap install dive`, with connections to Docker executables and daemon. The README cautions that the Snap method is not recommended when Docker was installed via `apt-get`. - **RHEL/CentOS**: download the `.rpm` release and install with `rpm -i`. - **Arch Linux**: available in the extra repository, install via `pacman -S dive`. - **macOS**: available via Homebrew (`brew install dive`) or MacPorts (`sudo port install dive`), or via the Darwin release build. - **Windows**: available via Chocolatey (`choco install dive`), Scoop (`scoop install main/dive`), winget (`winget install --id wagoodman.dive`), or the Windows release build. - **Go tools**: `go install github.com/wagoodman/dive@latest` (requires Go 1.10 or higher; the version output may not be accurate when installed this way). - **Nix/NixOS**: `nix-env -iA nixos.dive` or `nix-env -iA nixpkgs.dive`. - **Docker image**: pull `docker.io/wagoodman/dive` or `ghcr.io/wagoodman/dive` and mount the Docker socket when running. For alternative runtimes such as Colima, the Docker host may need to be set, for example: ```bash export DOCKER_HOST=$(docker context inspect -f '{{ .Endpoints.docker.Host }}') ``` ## Key bindings The interactive UI includes key bindings for quitting, switching between layer and file tree views, filtering files, scrolling, collapsing directories, and toggling visibility of added/removed/modified/unmodified files. Common bindings include Tab to switch views, Ctrl+F to filter files, Space to collapse/uncollapse a directory, and Ctrl+A/Ctrl+R/Ctrl+M/Ctrl+U to show or hide file change types. ## Configuration No configuration is required, but a YAML config file can override defaults. Example settings include the container engine (`docker` or `podman`), error handling, logging, key bindings, diff view defaults, file tree behavior such as collapse state and pane width, and layer view aggregation defaults. dive searches for configs in `$XDG_CONFIG_HOME/dive/*.yaml`, `$XDG_CONFIG_DIRS/dive/*.yaml`, `~/.config/dive/*.yaml`, and `~/.dive.yaml`; `.yml` is also accepted.