Ansible Playbook Grapher maps playbook structure into SVG, Mermaid and JSON

The problem is a playbook directory nobody can hold in their head

The stated purpose is narrow: a command line tool to create a graph representing your Ansible playbooks, plays, tasks and roles, with the aim of producing an overview you can use as documentation. That framing decides who this suits. If you want to watch what happened on a host during a run, this is the wrong tool, because nothing in the described feature set promises execution feedback. The likely user is an engineer who inherited a directory of playbooks and needs to see its shape: which roles a play pulls in, which tasks repeat, how much sits behind a single entry point. Tag filters, role grouping and the hiding of empty plays exist to make that shape readable, not to report outcomes. The tool also names system administrators among its intended audience, which matches the case where a runbook is shared between the people who wrote it and the people who have to maintain it.

Three renderers that each drop something different

Three renderers are available, and each gives up a different capability. The default graphviz renderer emits SVG and is described as having more features than the others. mermaid-flowchart emits Mermaid text that can be embedded directly in Markdown and rendered by GitHub and other integrations, and it is the only renderer listed as supporting a change of graph orientation. json writes a structured representation of the graph against a published schema, which the project points at as the route to building your own renderer outside the grapher. The comparison table makes the trade-off plain. Clicking a node to open the underlying file and highlighting related nodes on hover work only in the SVG. The Mermaid output supports neither, and the JSON output carries the file location in the output rather than in an interactive viewer. Collapsible play, role and block nodes are an SVG feature as well, so choosing Mermaid or JSON is choosing a flatter picture.

Installing the grapher without breaking your Ansible environment

Installation is a package install, but the project is insistent about isolation. Python 3.10 is the stated floor, and earlier versions might work while remaining explicitly untested. A virtual environment is described as highly recommended, because the grapher depends on specific versions of ansible-core that may not be installed in your environment and may cause trouble with older Ansible releases, a risk that grew when the ansible package was split. The recommended route uses uv, which installs the command as an isolated tool:

uv tool install ansible-playbook-grapher

Using pip instead is equally short:

pip install ansible-playbook-grapher

An unpublished version can be installed straight from the repository:

uv tool install "ansible-playbook-grapher @ git+https://github.com/haidaraM/ansible-playbook-grapher"

pip install "ansible-playbook-grapher @ git+https://github.com/haidaraM/ansible-playbook-grapher"

Graphviz is a separate requirement and only matters if you plan to use the graphviz renderer:

sudo apt-get install graphviz # or yum install or brew install

The maintainer states an intent to respect the Red Hat Ansible Engine Life Cycle when choosing which Ansible version is supported.

Your first run produces an SVG you are meant to open in a browser

The first real use takes a playbook path and writes a graph. The usage example points at a fixture playbook:

ansible-playbook-grapher tests/fixtures/example.yml

What comes back is an SVG whose nodes represent playbooks, plays, tasks and roles. Opening it in a browser, which the documentation recommends, is what activates the interactive layer. Clicking or hovering a node highlights everything related to it, and clicking a role selects its tasks when `--include-role-tasks` is set. A double click opens the matching file or folder, because a browser will normally download a YAML file rather than render it. Passing `--open-protocol-handler vscode` changes that behaviour: folders open for roles other than include_role, files open for the other node types, and the cursor lands on the exact task position in the file. A custom protocol is possible too, through `--open-protocol-handler custom` with `--open-protocol-custom-formats '{}'`. For long playbooks, `--collapsible-nodes` collapses play, role and block nodes so the graph stays navigable.

The ansible-core pin decides whether the install resolves at all

The packaging metadata pins ansible-core to a range that starts at 2.16 and stops below 2.18.3, alongside graphviz>=0.18,<1, colour<1, lxml<7 and svg.path<8, and the package itself requires Python 3.10 or newer. The practical consequence is that an environment holding a newer ansible-core will not resolve cleanly against these constraints, and a shared system interpreter is exactly the situation the virtual environment advice exists to prevent. The build tooling mirrors that separation. The Makefile builds with uv build, uses a venv-test-install directory for its install test, and runs the test suite from a dedicated tests directory, and carries a comment explaining that side effects from Ansible force the test files to run in a fixed order. For an organisation running several ansible-core versions side by side, that means each one needs its own environment with the grapher installed into it.

What the graph cannot tell you

Several gaps deserve to be stated plainly. Variable interpolation is offered only when possible, so a graph of a heavily parameterised playbook will not show every resolved value. Nothing in the feature list covers execution: there is no per-host result, no timing, and no indication of which task failed, so the output is a static picture of structure rather than of behaviour. The Mermaid result has to be checked by hand, because the comparison table marks its tests as manual and requiring a parser, while the SVG and JSON outputs are tested automatically. Grouping roles by name, supported by both the graphviz and mermaid renderers, deliberately merges roles that share a name, which can conceal the difference between two identically named roles living in different collections. Plays with nothing visible in them are removed only when you ask for that with a flag.

Two alternatives: a custom renderer, or Mermaid inside your docs

There are two credible alternatives, and they differ in kind rather than in price. The first is to use the JSON output as data rather than as a picture. Because the JSON representation carries the whole graph, including file locations, and ships with a schema kept under tests/fixtures/json-schemas, a team can build its own rendering pipeline instead of accepting the bundled SVG or Mermaid output. That costs more up front, and the resulting output then has to be verified by hand, but it is the only route to a layout that matches an existing documentation site. The second alternative is the Mermaid renderer for anything that lives in Markdown or on GitHub, where SVG interaction is unavailable in any case. The project also credits Ansible Inventory Grapher as the inspiration for its own approach, though the documentation offers no feature comparison between the two projects, so the reasonable check is to run both over the same playbooks rather than assume one replaces the other.

Release cadence in bursts, and a licence that follows the output

Version 2.11.1 is the current release, dated 2026-08-01, following 2.11.0 on the same day and 2.10.1 from 2025-11-10. The last push was on 2026-10-01, so the repository is not archived and development is recent, but the gap between the 2.10.1 and 2.11.0 releases shows the release line moving in bursts rather than on a fixed calendar. The project classifies itself as Production/Stable and names developers and system administrators as its intended audience. The licence is GPL-3.0-or-later, which is the part most likely to need a decision before you ship anything: that licence applies to redistribution of the tool itself, so anyone shipping or embedding the grapher should read the licence text before packaging it.

Editorial conclusion

Adopt ansible-playbook-grapher when you need a static map of playbook structure for documentation and the ansible-core range from 2.16 to below 2.18.3 fits your environment. Do not adopt it to trace what a run actually did. Before committing, check that your installed ansible-core resolves against that pinned range and that Graphviz is available if you intend to use the default renderer.

Frequently asked questions

Official sources

1. haidaraM/ansible-playbook-grapher on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases