Repository files navigation

pydot is a Python interface to Graphviz and its DOT language. You can usepydot to create, read, edit, and visualize graphs.

• It's made in pure Python, with only one dependency – pyparsing – other than Graphviz itself.
• It's compatible withnetworkx, which can convert its graphs topydot.

To see what Graphviz is capable of, check theGraphviz Gallery!

• Python: The latest version of pydot supports Python 3.9+. It may work with Python 3.6-3.8, but we can't guarantee full support. If you're using one of these older versions, feel free to experiment, but we won't be able to address issues specific to them. Older versions of pydot are also an option.
• pyparsing: used only forloading DOT files, installed automatically duringpydot installation.
• GraphViz: used to render graphs in a variety of formats, including PNG, SVG, PDF, and more.Should be installed separately, using your system'spackage manager, something similar (e.g.,MacPorts), or fromits source.

• Latest release, fromPyPI:

  pip install pydot

• Current development code, from this repository:

  pip install git+https://github.com/pydot/pydot.git

• Development installation, to modify the code or contribute changes:

  # Clone the repositorygit clone https://github.com/pydot/pydotcd pydot# (Optional: create a virtual environment)python3 -m venv _venv. ./_venv/bin/activate# Make an editable install of pydot from the source treepip install -e.

No matter what you want to do withpydot, you'll need some input to start with. Here are the common ways to get some data to work with.

Let's say you already have a fileexample.dot (based on anexample from Wikipedia):

graph my_graph {bgcolor="yellow";    a [label="Foo"];    b [shape=circle];    a-- b-- c [color=blue];}

You can read the graph from the file in this way:

importpydotgraphs=pydot.graph_from_dot_file("example.dot")graph=graphs[0]

Use this method if you already have a string describing a DOT graph:

importpydotdot_string="""graph my_graph {    bgcolor="yellow";    a [label="Foo"];    b [shape=circle];    a -- b -- c [color=blue];}"""graphs=pydot.graph_from_dot_data(dot_string)graph=graphs[0]

This is where the cool stuff starts. Use this method if you want to build new graphs with Python code.

importpydotgraph=pydot.Dot("my_graph",graph_type="graph",bgcolor="yellow")# Add nodesmy_node=pydot.Node("a",label="Foo")graph.add_node(my_node)# Or, without using an intermediate variable:graph.add_node(pydot.Node("b",shape="circle"))# Add edgesmy_edge=pydot.Edge("a","b",color="blue")graph.add_edge(my_edge)# Or, without using an intermediate variable:graph.add_edge(pydot.Edge("b","c",color="blue"))

You can use these basic building blocks in your Python programto dynamically generate a graph. For example, start with abasicpydot.Dot graph object, then loop through your dataas you add nodes and edges. Use values from your data as labels todetermine shapes, edges and so on. This allows you to easily createvisualizations of thousands of related objects.

NetworkX has conversion methods for pydot graphs:

importnetworkximportpydot# See NetworkX documentation on how to build a NetworkX graph.graph=networkx.drawing.nx_pydot.to_pydot(my_networkx_graph)

You can now further manipulate your graph using pydot methods:

Add more nodes and edges:

graph.add_edge(pydot.Edge("b","d",style="dotted"))

Edit attributes of graphs, nodes and edges:

graph.set_bgcolor("lightyellow")graph.get_node("b")[0].set_shape("box")

Here are three different output options:

If you just want to save the image to a file, use one of thewrite_* methods:

graph.write_png("output.png")

If you need to further process the image output, thecreate_* methods will get you a Pythonbytes object:

output_graphviz_svg=graph.create_svg()

There are two different DOT strings you can retrieve:

• The "raw" pydot DOT: This is generated the fastest and willusually still look quite similar to the DOT you put in. It isgenerated by pydot itself, without calling Graphviz.

  # As a string:output_raw_dot=graph.to_string()# Or, save it as a DOT-file:graph.write_raw("output_raw.dot")

• The Graphviz DOT: You can use it to check how Graphviz lays outthe graph before it produces an image. It is generated byGraphviz.

  # As a bytes literal:output_graphviz_dot=graph.create_dot()# Or, save it as a DOT-file:graph.write_dot("output_graphviz.dot")

NetworkX has a conversion method for pydot graphs:

my_networkx_graph=networkx.drawing.nx_pydot.from_pydot(graph)

For more help, see the docstrings of the various pydot objects andmethods. For example,help(pydot),help(pydot.Graph) andhelp(pydot.Dot.write).

Moredocumentation contributions welcome.

pydot uses Python's standardlogging module. To see the logs,assuming logging has not been configured already:

>>> import logging>>> logging.basicConfig(level=logging.DEBUG)>>> import pydotDEBUG:pydot:pydot initializingDEBUG:pydot:pydot <version>DEBUG:pydot.core:pydot core module initializingDEBUG:pydot.dot_parser:pydot dot_parser module initializing

Warning: WhenDEBUG level logging is enabled,pydot may log thedata that it processes, such as graph contents or DOT strings. This cancause the log to become very large or contain sensitive information.

• Check out thePython logging documentation and thelogging_tree visualizer.
• pydot does not add any handlers to its loggers, nor does it setupor modify your root logger. Thepydot loggers are created with thedefault levelNOTSET.
• pydot registers the following loggers:
  • pydot: Parent logger. Emits a few messages during startup.
  • pydot.core: Messages related to pydot objects, Graphviz executionand anything else not covered by the other loggers.
  • pydot.dot_parser: Messages related to the parsing of DOT strings.

Distributed under theMIT license.

The modulepydot._vendor.tempfileis based on the Python 3.12 standard library moduletempfile.py,Copyright © 2001-2023 Python Software Foundation. All rights reserved.Licensed under the terms of thePython-2.0 license.

Current maintainer(s):

• Łukasz Łapiński <lukaszlapinski7 (at) gmail (dot) com>

Past maintainers:

• Sebastian Kalinowski <sebastian (at) kalinowski (dot) eu> (GitHub: @prmtl)
• Peter Nowee <peter (at) peternowee (dot) com> (GitHub: @peternowee)

Original author: Ero Carrera <ero (dot) carrera (at) gmail (dot) com>