DEV Community

Cover image for How to Fix "Graphviz DOT Engine Not Found" and Other PlantUML Setup Bottlenecks
Jimmy Zhou
Jimmy Zhou

Posted on

How to Fix "Graphviz DOT Engine Not Found" and Other PlantUML Setup Bottlenecks

#plantuml #devops #productivity

If you use PlantUML for diagram-as-code workflows, you have likely run into this frustrating error when trying to render a class or activity diagram:

Cannot find Graphviz. You should install Graphviz and set the GRAPHVIZ_DOT environment variable.
Enter fullscreen mode Exit fullscreen mode

While PlantUML is completely free and open-source, getting it to run smoothly across a team often hits snag points around local dependencies.

Here is a quick guide on how to fix common local environment issues—and how to bypass them entirely if you want zero setup overhead.

1. Quick Fix: Configuring Graphviz Environment Variables

PlantUML uses Java for its core engine, but it relies on Graphviz (DOT engine) to compute layouts for structural diagrams (like Class, Component, and State diagrams).

If your IDE extension or CLI cannot render diagrams, follow these platform-specific fixes:

macOS (via Homebrew) 

# 1. Install Graphviz
brew install graphviz

# 2. Verify installation path (usually /opt/homebrew/bin/dot or /usr/local/bin/dot)
which dot

# 3. Add to your shell profile (.zshrc or .bash_profile)
export GRAPHVIZ_DOT="/opt/homebrew/bin/dot"
Enter fullscreen mode Exit fullscreen mode

Windows (PowerShell) 

# 1. Install via winget or Chocolatey
winget install Graphviz.Graphviz

# 2. Set user environment variable (restart terminal/IDE after running)
[System.Environment]::SetEnvironmentVariable("GRAPHVIZ_DOT", "C:\Program Files\Graphviz\bin\dot.exe", "User")
Enter fullscreen mode Exit fullscreen mode

2. Java Runtime (JRE) Mismatches

Because PlantUML is built on Java, missing or outdated JRE versions cause execution fails in VS Code or JetBrains extensions.

Verify your active Java installation:

java -version
Enter fullscreen mode Exit fullscreen mode

If you see command not found, install an OpenJDK distribution (version 11 or higher is recommended):

# macOS
brew install openjdk

# Ubuntu/Debian
sudo apt update && sudo apt install default-jre
Enter fullscreen mode Exit fullscreen mode

3. The Zero-Setup Alternative: Browser-Based Renders

Managing local JRE installations, Graphviz executables, and IDE extensions across a distributed team often introduces unnecessary onboarding friction.

If you want to skip local installation hurdles altogether, you can use modern browser-native editors. For instance, tools like Visual Paradigm VPasCode render PlantUML scripts directly in the cloud without requiring local Java or Graphviz drivers.

Why Teams Shift to Cloud Diagramming:

  • Zero Local Installs: Write and render PlantUML, Mermaid, or Graphviz code instantly in any browser.
  • Language Auto-Detection: Paste raw diagram scripts without manually selecting language parsers.
  • AI-Assisted Repair: Instantly debug broken PlantUML syntax with AI code diffs.

Want to Learn More?

If you are evaluating diagramming tools for your engineering team, check out a complete breakdown on PlantUML open-source licensing, hidden TCO, and free cloud editors.

Top comments (0)