What is ansible-inventory-grapher?
ansible-inventory-grapher is a command-line tool that generates visual graphs of your Ansible inventory — showing groups, hosts, and their relationships. It outputs DOT format that you render with Graphviz into PNG, SVG, or PDF diagrams.
Installation
# Install via pip
pip install ansible-inventory-grapher
# Install Graphviz (needed to render graphs)
# Ubuntu/Debian
sudo apt install graphviz
# RHEL/CentOS/Fedora
sudo dnf install graphviz
# macOS
brew install graphviz
Basic Usage
# Generate a DOT graph from your inventory
ansible-inventory-grapher -i inventory/hosts all | dot -Tpng -o inventory.png
This reads your inventory, generates a DOT graph, and pipes it to Graphviz to create a PNG image.
Example Inventory
# inventory/hosts
[webservers]
web1 ansible_host=192.168.1.10
web2 ansible_host=192.168.1.11
[dbservers]
db1 ansible_host=192.168.1.20
db2 ansible_host=192.168.1.21
[loadbalancers]
lb1 ansible_host=192.168.1.5
[production:children]
webservers
dbservers
loadbalancers
[production:vars]
env=production
ansible_user=deploy
Generate the Graph
# PNG output
ansible-inventory-grapher -i inventory/hosts all | dot -Tpng -o inventory.png
# SVG output (scalable, good for docs)
ansible-inventory-grapher -i inventory/hosts all | dot -Tsvg -o inventory.svg
# PDF output
ansible-inventory-grapher -i inventory/hosts all | dot -Tpdf -o inventory.pdf
Graph a Specific Group
# Only show webservers group
ansible-inventory-grapher -i inventory/hosts webservers | dot -Tpng -o webservers.png
# Only show production hierarchy
ansible-inventory-grapher -i inventory/hosts production | dot -Tpng -o production.png
Show Variables on the Graph
# Include variables in the graph
ansible-inventory-grapher -i inventory/hosts all -a "rankdir=LR;" | dot -Tpng -o inventory-vars.png
Customize Graph Appearance
Pass Graphviz attributes to change the layout:
# Horizontal layout (left to right)
ansible-inventory-grapher -i inventory/hosts all \
-a "rankdir=LR;" | dot -Tpng -o horizontal.png
# Custom node colors
ansible-inventory-grapher -i inventory/hosts all \
-a "rankdir=TB; node [shape=box, style=filled, fillcolor=lightblue];" \
| dot -Tpng -o styled.png
Use with Dynamic Inventory
# AWS EC2 dynamic inventory
ansible-inventory-grapher -i aws_ec2.yml all | dot -Tpng -o aws-inventory.png
# Any dynamic inventory script
ansible-inventory-grapher -i inventory.py all | dot -Tpng -o dynamic.png
Automate Diagram Generation
Add to your CI/CD or Makefile:
# Makefile
docs/inventory.png: inventory/hosts
ansible-inventory-grapher -i $< all | dot -Tpng -o $@
docs: docs/inventory.png
Use Cases
- Documentation — Auto-generate infrastructure diagrams for wikis and runbooks
- Debugging — Spot misplaced hosts, wrong group membership, or inheritance issues
- Onboarding — Help new team members understand inventory structure instantly
- Auditing — Verify group hierarchy before running playbooks on production
Alternative: ansible-inventory --graph
Ansible includes a built-in text-based view:
ansible-inventory -i inventory/hosts --graph
Output:
@all:
|--@production:
| |--@webservers:
| | |--web1
| | |--web2
| |--@dbservers:
| | |--db1
| | |--db2
| |--@loadbalancers:
| | |--lb1
|--@ungrouped:
This is simpler but doesn't produce visual diagrams.
Related Articles
- Ansible Tutorial for Beginners — Getting started
- Ansible Best Practices — Directory structure and organization
- ARA Records Ansible — Playbook reporting dashboard
- Ansible Facts — System information gathering
Conclusion
ansible-inventory-grapher turns your inventory into a visual diagram in one command. Install it with pip install ansible-inventory-grapher, pipe to Graphviz, and you have instant documentation of your infrastructure.