Skip to content

Installation Guide

Using an AI assistant?

You don't need this page. Follow Use TerraVision with AI assistants: install Graphviz and Git (and uv, except for Claude Desktop on Windows and macOS), then connect Claude, Codex, Gemini or Copilot, which install TerraVision themselves.

System Requirements

  • Python 3.11+ — download; not needed separately if you install with uv, which fetches one
  • Terraform 1.x (v1.0.0 or higher) — download; not required for JSON graph sources or --planfile mode
  • Git — download
  • Graphviz — download
  • Ollama (Optional — only for local AI refinement)
  • wslu (Optional — required only on WSL if you use --show to auto-open diagrams)

Note: If you use the --planfile and --graphfile options to provide pre-generated Terraform outputs, Terraform itself does not need to be installed. Only Python, Graphviz, and Git are required. See the Usage Guide for details. The same applies when drawing from a JSON graph (.tvg.json), which never runs Terraform.

Step 1: Install External Dependencies

Graphviz

macOS: 

brew install graphviz

Ubuntu/Debian: 

sudo apt update
sudo apt install graphviz
# Ubuntu 26.04 and later only (also Debian 14 "forky"/testing).
# Skip on older releases such as Ubuntu 24.04: graphviz already includes it.
sudo apt install libgvplugin-neato-layout8

Fedora/RHEL: 

sudo dnf install graphviz

Windows: any one of these, or the installer or ZIP archive from https://graphviz.org/download/ 

scoop install graphviz
choco install graphviz
winget install --id Graphviz.Graphviz

Scoop and Chocolatey put dot on your PATH. winget and the graphviz.org installer do not, so dot -V in a terminal reports it missing, but TerraVision (0.48.2 and later) finds Graphviz in C:\Program Files\Graphviz\bin by itself. Only if you installed Graphviz somewhere else, add its bin folder to your PATH: 

$gv = "D:\Tools\Graphviz\bin"   # wherever dot.exe is
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$gv", "User")
Then open a new terminal, and restart any app that launches TerraVision's MCP server (Claude Code, Claude Desktop, Cursor).

No admin rights, or Graphviz isn't in your organisation's Artifactory or Nexus? Download the ZIP archive from https://graphviz.org/download/, unpack it into a folder you own (such as %USERPROFILE%\Tools\Graphviz), and add its bin folder to your PATH as above: a user-level PATH needs no admin rights.

macOS and Linux without admin rights: build Graphviz from source into your home folder. Download a release from https://graphviz.org/download/source/, then: 

tar xf graphviz-*.tar.gz && cd graphviz-*/
./configure --prefix="$HOME/.local"
make && make install
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
You need a C compiler (on macOS, the Xcode Command Line Tools). TerraVision also needs two optional parts of Graphviz: expat, for the HTML labels its diagrams use, and cairo with pango, for PNG output. ./configure prints a summary of what it found; if they are missing, install their development packages or build them into the same prefix first. To check, run dot -Tpng:: it answers "not recognized" and then lists the PNG renderers it has, which must include png:cairo:cairo. On Linux, the precompiled binaries attached to Graphviz's GitLab releases are another option. If none of this is open to you, ask your IT team.

Verify installation: 

dot -V

Git

Most systems have Git pre-installed. Verify: 

git --version

If not installed: brew install git (macOS), sudo apt install git (Ubuntu/Debian), sudo dnf install git (Fedora/RHEL), winget install --id Git.Git or choco install git (Windows), or download from https://git-scm.com/downloads

Terraform

macOS: 

brew tap hashicorp/tap
brew install hashicorp/terraform

Ubuntu/Debian: 

wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform

Windows: any one of these, or the download from https://developer.hashicorp.com/terraform/install 

winget install --id Hashicorp.Terraform
choco install terraform
scoop install terraform

OpenTofu works as a drop-in alternative: install it from https://opentofu.org/docs/intro/install/ (macOS: brew install opentofu) and pass --engine tofu, or leave --engine auto to detect whichever is installed.

Verify installation: 

terraform version
# Must show v1.0.0 or higher

WSL (Windows Subsystem for Linux)

If you run TerraVision under WSL and intend to use the --show flag to auto-open generated diagrams, install wslu:

sudo apt install wslu

Why: WSL ships without a real Linux desktop, so the standard xdg-open lookup chain has no application database to consult and fails silently. The wslu package provides wslview, which calls back into Windows and uses your host file associations (PNG → Photos, SVG → browser, etc.). TerraVision automatically detects WSL at runtime and routes opens through wslview; without it the diagram still gets generated correctly, you just have to open the file yourself.

If wslu isn't installed, TerraVision prints a one-line sudo apt install wslu hint when --show is used. You can also skip --show entirely and open the output file from Windows Explorer or your editor.

Step 2: Install TerraVision

TerraVision is published to PyPI, so a single command installs the CLI and wires it up on your PATH on macOS, Linux, and Windows.

Using pipx (preferred — isolated environment)

pipx installs the CLI into its own isolated virtualenv so it can't clash with other Python tooling on your system.

# Install pipx first if you don't have it
# macOS:          brew install pipx && pipx ensurepath
# Ubuntu/Debian:  sudo apt install pipx && pipx ensurepath
# Windows:        python -m pip install --user pipx && python -m pipx ensurepath

pipx install terravision
terravision --version

Using uv

uv also installs the CLI into its own environment, and downloads a suitable Python if yours is older than 3.11.

# Install uv first if you don't have it
# macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh   (or: brew install uv)
# Windows:      powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv tool install terravision
terravision --version

# Or run it without installing
uvx terravision --version

If terravision is not found afterwards, run uv tool update-shell and open a new terminal.

Using pip (if you're already in a virtualenv)

pip install terravision
terravision --version

Outside a virtualenv, recent Ubuntu, Debian and Homebrew Pythons refuse pip install with an externally-managed-environment error. Create one first (python3 -m venv ~/.venvs/terravision, then use ~/.venvs/terravision/bin/pip), or use pipx or uv.

Upgrading

pipx upgrade terravision, uv tool upgrade terravision or pip install --upgrade terravision pulls the latest release from PyPI.

Optional: MCP server support

To let AI agents drive TerraVision via the Model Context Protocol, install the mcp extra:

# pipx, new install
pipx install "terravision[mcp]"

# pipx, existing install (pip install won't work inside a pipx environment)
pipx inject terravision mcp

# uv, new or existing install
uv tool install "terravision[mcp]"

# pip
pip install "terravision[mcp]"

Then terravision mcp --help should work. Without the extra, every other command is unaffected.

Method 2: Docker (Zero Setup)

If you don't want to install Python, Graphviz, and Terraform locally, you can run everything inside the official Docker image. This is also the recommended method for containerized CI/CD systems.

Pull the image

docker pull patrickchugh/terravision:latest

Or build it yourself:

git clone https://github.com/patrickchugh/terravision.git && cd terravision
docker build -t patrickchugh/terravision .

Run it against your Terraform code

Mount your project into the container so it can see your .tf files and write output back:

# Local directory
docker run --rm -it -v "$(pwd):/project" patrickchugh/terravision \
  draw --source /project/yourfiles/ --varfile /project/your.tfvars

# Remote Git repository with subfolder
docker run --rm -it -v "$(pwd):/project" patrickchugh/terravision \
  draw --source https://github.com/your-repo/terraform-examples.git//mysubfolder/

Run the MCP server from it

The image includes the MCP server; see MCP server for the client configuration.

Passing cloud credentials

If Terraform needs credentials to run terraform plan, pass them into the container. For AWS:

# Mount your AWS credentials folder
docker run --rm -it -v "$(pwd):/project" \
  -v ~/.aws:/home/terravision/.aws:ro \
  patrickchugh/terravision draw --source /project/yourfiles/

# Or pass credentials as environment variables
docker run --rm -it -v "$(pwd):/project" \
  -e AWS_ACCESS_KEY_ID=your-access-key \
  -e AWS_SECRET_ACCESS_KEY=your-secret-key \
  patrickchugh/terravision draw --source /project/yourfiles/

Skip credentials entirely

Use --planfile and --graphfile with pre-generated Terraform plan output to bypass terraform plan altogether. See Pre-Generated Plan Input.

Pinning a Terraform version

The image includes tfenv, so you can install and select a specific Terraform version at runtime via TFENV_TERRAFORM_VERSION:

docker run --rm -it -v "$(pwd):/project" \
  -e TFENV_TERRAFORM_VERSION=1.9.8 \
  patrickchugh/terravision draw --source /project/yourfiles/

If TFENV_TERRAFORM_VERSION is omitted, the container runs terravision directly with the image's default Terraform.

Method 3: Nix (Reproducible Shell)

If you have Nix installed with flakes enabled, you can get a fully reproducible development shell with TerraVision and every dependency pinned.

Enter a dev shell

git clone https://github.com/patrickchugh/terravision.git && cd terravision
nix develop

This gives you terravision, graphviz, terraform, and git in your PATH with no system-level install needed.

One-shot run without cloning

nix run github:patrickchugh/terravision -- draw --source /path/to/terraform --show

Method 4: Install from Source with Poetry (For Contributors)

Use this method if you plan to hack on TerraVision itself. It's the workflow used by CI and every maintainer.

Install Poetry

macOS/Linux: 

curl -sSL https://install.python-poetry.org | python3 -

Windows: 

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Install TerraVision with Poetry

# Clone repository
git clone https://github.com/patrickchugh/terravision.git
cd terravision

# Install dependencies in an isolated virtual environment
poetry install

# Activate the venv (drop the `poetry run` prefix for subsequent commands)
eval $(poetry env activate)
terravision --version

# Or use `poetry run` for individual commands without activating
poetry run terravision --version

See the Contributing Guide for coding standards, tests, and the PR process.

Step 3: Verify Installation

Run a test to ensure everything is working:

# Check TerraVision version
terravision --version

# Check help
terravision --help

# Verify all dependencies
terraform version
git --version
dot -V
python --version

Optional: Install Ollama (For Local AI Refinement)

If you want to use local AI-powered diagram refinement:

Install Ollama

macOS: 

brew install ollama

Linux: 

curl -fsSL https://ollama.com/install.sh | sh

Windows: Download from https://ollama.com/download

Setup Ollama

# Start Ollama server (runs automatically on macOS/Linux after install)
ollama serve

# Pull the default model (llama3)
ollama pull llama3

# Optional: Keep model loaded longer (default is 5 minutes)
export OLLAMA_KEEP_ALIVE=1h

# Verify Ollama is running
curl http://localhost:11434/api/tags

Using a different model: Edit OLLAMA_MODEL in modules/config/cloud_config_<provider>.py (default llama3) to any tag you've pulled — llama3.1, mistral, qwen2.5, etc. Make sure the corresponding ollama pull <model> has been run first, otherwise the first chat call will return 404 and TerraVision falls back to non-AI rendering.

Troubleshooting Installation

Python Version Issues

# Check Python version
python --version

# If Python 3.11+ not available, install it
# macOS
brew install python@3.11

# Ubuntu
sudo apt-get install python3.11

Permission Issues (Linux/macOS)

If pip install terravision fails with permission errors, use pipx (recommended) or fall back to a user install / virtualenv:

# Preferred: isolated install via pipx (no sudo ever needed)
pipx install terravision

# Or user install
pip install --user terravision

# Or inside a virtualenv
python -m venv venv
source venv/bin/activate
pip install terravision

PATH Issues

If terravision command is not found:

# Add to PATH temporarily
export PATH=$PATH:/path/to/terravision

# Add to PATH permanently (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH=$PATH:/path/to/terravision' >> ~/.bashrc
source ~/.bashrc

Graphviz Not Found

If you get "dot command not found" error:

# Verify Graphviz installation
which dot

# If not found, reinstall Graphviz
# macOS
brew reinstall graphviz

# Ubuntu
sudo apt-get install --reinstall graphviz

Next Steps