graphviz2drawio

Convert graphviz (dot) files to draw.io / lucid (mxGraph) format. Beautiful and editable graphs in your favorite editor.

Installation

macOS

graphviz2drawio can be installed with Homebrew:

brew install graphviz2drawio

Linux

It is recommended to use uv or pipx to install and run the CLI tool in an isolated environment. If you wish to use the library, you can install with pip instead.

Note that the graphviz library is required before installing this package.

With uv

Ubuntu / Debian

sudo apt update
sudo apt install graphviz graphviz-dev
uv tool install graphviz2drawio
# To update: uv tool upgrade graphviz2drawio

Fedora

sudo dnf install graphviz graphviz-devel
uv tool install graphviz2drawio
# To update: uv tool upgrade graphviz2drawio

With pipx

Ubuntu / Debian

sudo apt update
sudo apt install pipx graphviz graphviz-dev
pipx install graphviz2drawio
# To update: pipx upgrade graphviz2drawio

Fedora

sudo dnf install pipx graphviz graphviz-devel
pipx ensurepath
pipx install graphviz2drawio
# To update: pipx upgrade graphviz2drawio

Anaconda

conda install conda-forge::graphviz2drawio

Usage

Run the conversion app on your graphviz file. For example, the command below will create converted files example1.xml and example2.xml.

graphviz2drawio example1.dot example2.dot

Alternatively, you can specify the output file (but only if there is a single input file)

graphviz2drawio example.dot -o /path/to/somewhere/new_name.xml

Output can also be sent to stdout by using the --stdout flag.

Graphs can be piped in from stdin and sent to stdout (default) or to a file with -o ....

Library Usage

from graphviz2drawio import graphviz2drawio

graph_to_convert = ...
xml = graphviz2drawio.convert(graph_to_convert)
print(xml)

where graph_to_convert can be any of a file path, file handle, string of dot language, or PyGraphviz.AGraph object

Troubleshooting

dot / Graphviz not found

graphviz2drawio uses PyGraphviz, which is 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 Installation), 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 install with uv, pip, or pipx. 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 uv or 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

Built With

• PyGraphviz - Python interface to Graphviz
• svg.path - SVG path objects and parser

Contributing

Pull requests and issue reports are welcome. For major changes, please open an issue first to discuss what you would like to change.

To see architectural and process diagrams please visit the deepwiki page

Thanks to all the people who have contributed to this project!

Development Setup

uv is used for packaging and dependency management.

git clone git@github.com:hbmartin/graphviz2drawio.git
cd graphviz2drawio
uv sync
# Replace with the actual path to your dot files
uv run python -m graphviz2drawio test/directed/hello.gv.txt

On macOS (Apple Silicon), pygraphviz compiles a C extension against Graphviz, and Homebrew's /opt/homebrew is not on the default compiler search path. If uv sync fails to build pygraphviz (clang error about missing graphviz/cgraph.h), install Graphviz and rebuild that package with the Homebrew paths:

brew install graphviz
CFLAGS="-I$(brew --prefix graphviz)/include" \
LDFLAGS="-L$(brew --prefix graphviz)/lib" \
uv sync --reinstall-package pygraphviz

Spec tests

Spec XMLs are stored separately for macOS and Linux because graph layout depends on platform font metrics. The spec test runner automatically compares against specs/mac/ on macOS and specs/linux/ on Linux. Each XML spec also has a matching draw.io-rendered PNG reference, and the test runner compares generated PNGs pixel by pixel.

The scripts invoke python3 directly, so run the native (macOS) variants through uv run so they resolve to the project venv. The spec_env.sh variants run inside Docker and already have the venv on PATH. Native spec testing and generation also require the draw.io CLI, for example from brew install --cask drawio on macOS.

uv run ./scripts/test_specs.sh test/ tmp_out/
./scripts/spec_env.sh ./scripts/test_specs.sh test/ tmp_out/
uv run ./scripts/generate_specs.sh test/ specs/mac/
./scripts/spec_env.sh ./scripts/generate_specs.sh test/ specs/linux/

Large or slow spec fixtures can be skipped by setting SPEC_TEST_EXCLUDES to comma- or whitespace-separated paths/globs. Patterns match paths relative to the platform spec directory, and basenames also work for convenience.

SPEC_TEST_EXCLUDES="twopi/twopi2.xml" uv run ./scripts/test_specs.sh test/ tmp_out/
SPEC_TEST_EXCLUDES="twopi2.xml,networkmap_*.xml" ./scripts/spec_env.sh ./scripts/test_specs.sh test/ tmp_out/

Roadmap

• Support compatible arrows
• Support multiple edges
• Support edges with links

Legal

© Harold Martin - released under GPLv3

diagrams.net is a trademark and draw.io is a registered trademark of JGraph Limited.