A command-line tool that visualizes multi-stage Dockerfiles as dependency graphs.
Uses Graphviz to generate visual representations of Docker build processes, helping you understand build dependencies, document architecture, and debug complex multi-stage builds.
The generated graph includes:
Nodes:
- All build stages
- Default build target (highlighted in grey)
- External images (with dashed borders)
Edges:
FROM ...dependencies → solid line with full arrowCOPY --from=...dependencies → dashed line with empty arrowRUN --mount=(.*)from=...dependencies → dotted line with diamond arrow
Supports multiple output formats (PDF, SVG, PNG), a legend, and layout customization options.
- A multi-stage Dockerfile
Run dockerfilegraph in your project directory to generate a Dockerfile.pdf with your build graph.
docker run --rm --user "$(id -u):$(id -g)" \ -v "$(pwd)":/workspace -w /workspace \ ghcr.io/patrickhoefler/dockerfilegraph
brew install patrickhoefler/tap/dockerfilegraph dockerfilegraph
Requirements: Graphviz installed locally
mise use -g github:patrickhoefler/dockerfilegraph dockerfilegraph
-
Native Build
Requirements: mise and Graphviz
mise install mise run build ./dockerfilegraph
-
Container Build
mise install mise run build-docker-image docker run \ --rm \ --user "$(id -u):$(id -g)" \ --workdir /workspace \ --volume "$(pwd)":/workspace \ dockerfilegraph
Common Flags:
--output svg|png|pdf- Choose your output format--legend- Add a legend explaining the notation--layers- Show all Docker layers--separate ubuntu,alpine- Display selected external images as separate nodes per usage, reducing edge clutter--target release,app- Only show stages required to build the given target(s), eliding everything else
All Available Options:
❯ dockerfilegraph --help
dockerfilegraph visualizes your multi-stage Dockerfile.
It creates a visual graph representation of the build process.
Usage:
dockerfilegraph [flags]
Flags:
-c, --concentrate concentrate the edges (default false)
-d, --dpi uint dots per inch of the PNG export (default 96)
-e, --edgestyle style of the graph edges, one of: default, solid (default default)
-f, --filename string name of the Dockerfile (default "Dockerfile")
-h, --help help for dockerfilegraph
--layers display all layers (default false)
--legend add a legend (default false)
-m, --max-label-length uint maximum length of the node labels, must be at least 4 (default 20)
-n, --nodesep float minimum space between two adjacent nodes in the same rank (default 1)
-o, --output output file format, one of: canon, dot, pdf, png, raw, svg (default pdf)
-r, --ranksep float minimum separation between ranks (default 0.5)
--scratch how to handle scratch images, one of: collapsed, hidden, separated (default collapsed)
--separate strings external images to display as separate nodes per usage (e.g. --separate ubuntu,alpine)
--target strings only show stages required to build the given target(s) (e.g. --target release,app)
-u, --unflatten uint stagger length of leaf edges between [1,u] (default 0)
--version display the version of dockerfilegraph
This project uses mise for tool version management and running common development tasks.
Quick Start:
# Install project tools mise install # Run linters and tests mise run check # Build the binary mise run build
Run mise tasks to see all available tasks.
Found a bug or have a feature request? Open an issue or submit a pull request.