Troubleshooting

dot / Graphviz not found

graphviz2drawio uses PyGraphviz, a binding around the system Graphviz installation — installing the Python package alone is not enough. If you see an ImportError for pygraphviz, or a runtime error about a missing dot executable, install Graphviz with your package manager first (see Getting Started), then confirm it is on your PATH:

dot -V

pygraphviz fails to build during installation

pygraphviz compiles a C extension against the Graphviz development headers, so those headers must be present before you pip / pipx install. On Debian / Ubuntu install graphviz-dev (or libgraphviz-dev); on Fedora install graphviz-devel.

On macOS (Apple Silicon) the Homebrew prefix /opt/homebrew is not on the default compiler search path, so the build can fail with a clang error about a missing graphviz/cgraph.h. Point the compiler at the Homebrew paths:

brew install graphviz
CFLAGS="-I$(brew --prefix graphviz)/include" \
LDFLAGS="-L$(brew --prefix graphviz)/lib" \
pip install --no-cache-dir --force-reinstall pygraphviz

UnableToParseGraphError

This is raised when Graphviz returns no SVG for your graph, which usually means the layout program could not lay the graph out (a missing layout engine or an invalid graph). Confirm Graphviz can render the file directly:

dot -Tsvg yourgraph.dot -o output.svg

If that command also fails, the problem is in your graph or your Graphviz installation rather than in graphviz2drawio.

Layout program not available

The -p / --program flag (default dot) selects a Graphviz layout engine. If you pass neato, circo, twopi, fdp, etc., that binary must be installed — most are bundled with Graphviz, but minimal installs may omit some. Verify with:

neato -V

UnicodeDecodeError on input files

graphviz2drawio reads files using your locale encoding by default and automatically retries as UTF-8 when that fails (a common case on non-UTF-8 Windows systems such as gbk / cp1252, see #105). If decoding still fails, pass the file’s actual encoding explicitly:

graphviz2drawio --encoding utf-8 yourgraph.dot

Unsupported Python version

graphviz2drawio requires Python 3.11 or newer. Check your interpreter with python --version, and prefer pipx for the CLI so it runs in its own isolated, compatible environment.

Other conversion errors

Errors such as MissingTitleError, MissingTextError, or CouldNotParsePathError mean Graphviz produced SVG that the parser did not expect for your particular graph. Please open an issue and include your diagram along with your Python and graphviz2drawio versions:

python --version
graphviz2drawio --version