Skip to main content

terraform-viz - Terraform Infrastructure Visualizer

PyPI version Python Support License: MIT

A simple, fast CLI tool for generating PNG visualizations of your Terraform infrastructure.

Overview

terraform-viz generates visual diagrams showing your Terraform resources, their dependencies, and relationships. Perfect for understanding complex infrastructure, documentation, and identifying potential issues.

Features

  • 🎨 PNG output - High-quality visualizations ready for documentation
  • 🔍 Flexible paths - Work with any Terraform directory
  • 📦 Plan support - Visualize specific plan files
  • 🧹 Clean operation - Optional intermediate file cleanup
  • 💬 Verbose mode - Detailed progress information with Rich formatting
  • ❌ Error handling - Clear error messages and suggestions
  • 🎯 Custom spacing - Adjustable node padding for optimal layouts

Installation

From PyPI (Recommended)

pip install terraform-viz
# or
uv add terraform-viz

From Source

git clone https://github.com/pedropcamellon/terraform-viz.git
cd terraform-viz
uv pip install -e .

Prerequisites

  1. Terraform - Must be available in PATH or specify path with --tf-path
  2. Graphviz - Only required for PNG output with -o flag
    • Install with: winget install graphviz (Windows) or brew install graphviz (macOS)

Usage

Quick Start

# Basic usage - generates timestamped PNG in output/
terraform-viz

# Custom output filename  
terraform-viz -o infrastructure.png

# Work with different Terraform directory
terraform-viz --tf-dir ../production

# Visualize a specific plan file
terraform-viz --plan-file tfplan

# Specify custom Terraform executable
terraform-viz --tf-path /path/to/terraform

# Verbose output with intermediate files kept
terraform-viz -v --keep-dot

# Adjust spacing between nodes
terraform-viz --node-padding 1.5

# ASCII output for terminal/CI-CD (no Graphviz needed!)
terraform-viz --ascii

Command Line Options

usage: terraform-viz [-h] [-o OUTPUT] [--tf-dir TF_DIR] [--tf-path TF_PATH] 
             [--keep-dot] [--verbose] [--node-padding NODE_PADDING] 
             [--plan-file PLAN_FILE]

Generate visualizations of Terraform infrastructure (ASCII by default, PNG with -o)

options:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        Output PNG file path (default: ASCII to terminal only)
  --tf-dir TF_DIR       Directory containing Terraform files (default: current directory)
  --tf-path TF_PATH     Path to Terraform executable or alias (default: terraform)
  --keep-dot            Keep intermediate DOT file after rendering
  --verbose, -v         Enable verbose output
  --node-padding NODE_PADDING
                        Spacing between nodes for PNG output (default: 1.0, larger = more spaced out)
  --plan-file PLAN_FILE
                        Path to Terraform plan file to visualize (optional)

How It Works

  1. Discovery - Locates Terraform executable (and Graphviz if generating PNG)
  2. Graph Generation - Runs terraform graph to create DOT format dependency graph
  3. Rendering - Displays ASCII diagram in terminal (default) or generates PNG with -o flag
  4. Cleanup - Optionally removes intermediate DOT file

Understanding the Output

ASCII Output (Default)

The ASCII diagram shows:

  • 📥 Variables - Input variables
  • 💎 Providers - Cloud/infrastructure providers
  • 🔍 Data Sources - External data being fetched
  • 📚 Modules - Terraform modules
  • 📦 Resources - Terraform resources
  • 📤 Outputs - Output values
  • └─► - Dependencies between resources

PNG Output (with -o flag)

The generated PNG shows:

  • Resources - Terraform resources (rectangles)
  • Data Sources - External data being fetched (diamonds)
  • Variables - Input variables (ovals)
  • Outputs - Output values (house shapes)
  • Dependencies - Arrows showing resource relationships

Both formats help you:

  • Understand resource dependencies
  • Identify circular dependencies
  • Visualize infrastructure complexity
  • Document your architecture

Troubleshooting

Common Issues

Terraform not found:

  • Check if Terraform is in PATH: where terraform (Windows) or which terraform (macOS/Linux)
  • Install Terraform or ensure it's in your PATH

Graphviz not found (only for PNG generation):

  • Check if Graphviz is in PATH: where dot (Windows) or which dot (macOS/Linux)
  • Install Graphviz with: winget install graphviz (Windows) or brew install graphviz (macOS)
  • Note: Not needed for ASCII output (default)

Empty visualization:

  • Check that you're in a directory with Terraform files (*.tf)
  • Ensure Terraform files are valid and can be parsed

Large file sizes:

  • Complex infrastructures generate large PNGs
  • Consider splitting large configurations into modules

Verbose Mode

Use -v flag to see detailed information:

  • Executable paths being used
  • Directory changes
  • File operations
  • Cleanup actions

Advanced Usage

Direct Graphviz Commands

You can also use the DOT file directly with Graphviz command-line tools:

# Generate different formats (run with --keep-dot first)
dot -Tsvg terraform_graph.dot -o graph.svg
dot -Tpng terraform_graph.dot -o graph.png  
dot -Tpdf terraform_graph.dot -o graph.pdf

# Generate interactive HTML
dot -Tsvg terraform_graph.dot | dot -Tcmapx > graph.map

Use: uv run python terraform_viz.py --tf-dir "C:/../dev" to visualize dev environment

Integration

Documentation

Perfect for including infrastructure diagrams in:

  • README files
  • Wiki pages
  • Architecture documents
  • Presentations

CI/CD

Can be automated in pipelines to:

  • Generate diagrams on infrastructure changes
  • Include in deployment reports
  • Archive infrastructure snapshots

ASCII Diagrams for Terminal/CI/CD

For headless environments or CI/CD pipelines, use the built-in --ascii flag to render diagrams directly in the terminal instead of Terraform's verbose plan output:

# Generate ASCII diagram to terminal
terraform-viz --ascii

# Save ASCII diagram to file
terraform-viz --ascii -o infrastructure.txt

# Use with different Terraform directory
terraform-viz --ascii --tf-dir ../production

# Combine with verbose mode
terraform-viz --ascii -v

Benefits:

  • No Graphviz installation required
  • Compact, readable diagrams in terminal output
  • Better alternative to Terraform's verbose plan format
  • Perfect for CI/CD logs and SSH sessions
  • Shows resource hierarchy and dependencies clearly

Example Output:

================================================================================
Terraform Infrastructure Diagram (ASCII)
================================================================================

VARIABLES:
  📥 var.instance_type

RESOURCES:
  📦 aws_instance.web
     └─► aws_security_group.allow_http
     └─► aws_subnet.main
  📦 aws_vpc.main
     └─► provider[aws]

OUTPUTS:
  📤 output.instance_ip
     └─► aws_instance.web

================================================================================
Total: 4 resources, 0 data sources, 7 dependencies
================================================================================

Development

Building & Testing

# Build package
uv build

# Test CLI (shows ASCII by default)
uv run terraform-viz --help

# Test ASCII mode (default)
uv run terraform-viz --tf-dir /path/to/terraform

# Test PNG generation
uv run terraform-viz --tf-dir /path/to/terraform -o output.png

Project Structure

terraform-viz/
├── .github/workflows/      # CI/CD pipelines
├── examples/               # Sample DOT files
├── src/terraform_viz/      # Source code
│   ├── cli.py             # CLI entry point
│   ├── config.py          # Configuration
│   ├── orchestrator.py    # Main orchestration
│   ├── renderer.py        # PNG rendering
│   ├── ascii_renderer.py  # ASCII rendering
│   ├── graph_generator.py # Terraform graph generation
│   ├── file_manager.py    # File operations
│   └── executables.py     # Executable finding
├── output/                # Generated visualizations
└── pyproject.toml        # Package configuration

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

Publishing to PyPI

For Maintainers

One-time setup:

  1. Configure PyPI Trusted Publishing at https://pypi.org/manage/account/publishing/
    • Project: terraform-viz
    • Owner: pedropcamellon
    • Repository: terraform-viz
    • Workflow: publish.yml

To release a new version:

# 1. Update version in pyproject.toml and CHANGELOG.md
# 2. Commit changes
git add pyproject.toml CHANGELOG.md
git commit -m "Release v0.2.0"
git push

# 3. Create and push tag
git tag v0.2.0
git push origin v0.2.0

# 4. Create GitHub release (triggers automatic PyPI publish)
gh release create v0.2.0 --title "v0.2.0" --notes-file CHANGELOG.md

The GitHub Action will automatically build and publish to PyPI.


License

MIT License - see LICENSE file for details.

Links

Metadata

Release files for terraform-viz 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for terraform-viz 0.2.0
File Size Uploaded Provenance Actions
terraform_viz-0.2.0.tar.gz 15.6 kB With provenance Details for terraform_viz-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for terraform-viz 0.2.0
File Interpreter ABI Platform Actions
terraform_viz-0.2.0-py3-none-any.whl Python 3 none any Details for terraform_viz-0.2.0-py3-none-any.whl

Total release size: 30.8 kB

Release files / terraform_viz-0.2.0.tar.gz

Download URL terraform_viz-0.2.0.tar.gz
Size 15.6 kB
Tags Source
SHA-256 checksum
How to use checksums
a0de15f3b2117182126f6f758b818468490a9bc8cb0d1bb7b2e4d14a065e93ca
BLAKE2b-256 checksum
How to use checksums
01218fc9293ea09279eceeaa8379093e0084ee9f06a76be5c29dbedb39f42bdc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 14, 2026.

Transparency log

Release files / terraform_viz-0.2.0-py3-none-any.whl

Download URL terraform_viz-0.2.0-py3-none-any.whl
Size 15.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
06016cf70a1c314576ef39bad31030dac30f029c92a090c818e59ee53cf77b35
BLAKE2b-256 checksum
How to use checksums
0a21539f5d4e400367b0ca477d19df8b9d39a2d2db32e3be09d77dfbf0e9a338
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 14, 2026.

Transparency log

Security for terraform-viz 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for terraform_viz-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page