API Reference

Graph Graph source code in the DOT language.
Digraph Directed graph source code in the DOT language.
Source Verbatim DOT source code string to be rendered by Graphviz.
graphviz.render Render file with Graphviz engine into format, return result filename.
graphviz.pipe Return data piped through Graphviz engine into format.
graphviz.view Open filepath with its default viewing application (platform-specific).

Note

The two main classes Graph and Digraph (for creating undirected vs. directed graphs) have exactly the same API. Their division reflects the fact that both graph types cannot be mixed.

Graph

class graphviz.Graph(name=None, comment=None, filename=None, directory=None, format=None, engine=None, encoding='utf-8', graph_attr=None, node_attr=None, edge_attr=None, body=None, strict=False)

Graph source code in the DOT language.

Parameters:
  • name – Graph name used in the source code.
  • comment – Comment added to the first line of the source.
  • filename – Filename for saving the source (defaults to name + '.gv').
  • directory – (Sub)directory for source saving and rendering.
  • format – Rendering output format ('pdf', 'png', …).
  • engine – Layout command used ('dot', 'neato', …).
  • encoding – Encoding for saving the source.
  • graph_attr – Mapping of (attribute, value) pairs for the graph.
  • node_attr – Mapping of (attribute, value) pairs set for all nodes.
  • edge_attr – Mapping of (attribute, value) pairs set for all edges.
  • body – Iterable of verbatim lines to add to the graph body.
  • strict (bool) – Rendering should merge multi-edges.

Note

All parameters are optional and can be changed under their corresponding attribute name after instance creation.

attr(kw=None, _attributes=None, **attrs)

Add a general or graph/node/edge attribute statement.

Parameters:
  • kw – Attributes target (None or 'graph', 'node', 'edge').
  • attrs – Attributes to be set (must be strings, may be empty).

See the usage examples in the User Guide.

clear(keep_attrs=False)

Reset content to an empty body, clear graph/node/egde_attr mappings.

Parameters:keep_attrs (bool) – preserve graph/node/egde_attr mappings
copy()

Return a copied instance of the object.

Returns:An independent copy of the current object.
directed

False

edge(tail_name, head_name, label=None, _attributes=None, **attrs)

Create an edge between two nodes.

Parameters:
  • tail_name – Start node identifier.
  • head_name – End node identifier.
  • label – Caption to be displayed near the edge.
  • attrs – Any additional edge attributes (must be strings).
edges(tail_head_iter)

Create a bunch of edges.

Parameters:tail_head_iter – Iterable of (tail_name, head_name) pairs.
encoding

The encoding for the saved source file.

engine

The layout commmand used for rendering ('dot', 'neato', …).

format

The output format used for rendering ('pdf', 'png', …).

node(name, label=None, _attributes=None, **attrs)

Create a node.

Parameters:
  • name – Unique identifier for the node inside the source.
  • label – Caption to be displayed (defaults to the node name).
  • attrs – Any additional node attributes (must be strings).
pipe(format=None, renderer=None, formatter=None)

Return the source piped through the Graphviz layout command.

Parameters:
  • format – The output format used for rendering ('pdf', 'png', etc.).
  • renderer – The output renderer used for rendering ('cairo', 'gd', …).
  • formatter – The output formatter used for rendering ('cairo', 'gd', …).
Returns:

Binary (encoded) stdout of the layout command.
Raises:
render(filename=None, directory=None, view=False, cleanup=False, format=None, renderer=None, formatter=None)

Save the source to file and render with the Graphviz engine.

Parameters:
  • filename – Filename for saving the source (defaults to name + '.gv')
  • directory – (Sub)directory for source saving and rendering.
  • view (bool) – Open the rendered result with the default application.
  • cleanup (bool) – Delete the source file after rendering.
  • format – The output format used for rendering ('pdf', 'png', etc.).
  • renderer – The output renderer used for rendering ('cairo', 'gd', …).
  • formatter – The output formatter used for rendering ('cairo', 'gd', …).
Returns:

The (possibly relative) path of the rendered file.
Raises:
  • ValueError – If format, renderer, or formatter are not known.
  • graphviz.RequiredArgumentError – If formatter is given but renderer is None.
  • graphviz.ExecutableNotFound – If the Graphviz executable is not found.
  • subprocess.CalledProcessError – If the exit status is non-zero.
  • RuntimeError – If viewer opening is requested but not supported.
save(filename=None, directory=None)

Save the DOT source to file. Ensure the file ends with a newline.

Parameters:
  • filename – Filename for saving the source (defaults to name + '.gv')
  • directory – (Sub)directory for source saving and rendering.
Returns:

The (possibly relative) path of the saved source file.
source

The DOT source code as string.

subgraph(graph=None, name=None, comment=None, graph_attr=None, node_attr=None, edge_attr=None, body=None)

Add the current content of the given sole graph argument as subgraph or return a context manager returning a new graph instance created with the given (name, comment, etc.) arguments whose content is added as subgraph when leaving the context manager’s with-block.

Parameters:
  • graph – An instance of the same kind (Graph, Digraph) as the current graph (sole argument in non-with-block use).
  • name – Subgraph name (with-block use).
  • comment – Subgraph comment (with-block use).
  • graph_attr – Subgraph-level attribute-value mapping (with-block use).
  • node_attr – Node-level attribute-value mapping (with-block use).
  • edge_attr – Edge-level attribute-value mapping (with-block use).
  • body – Verbatim lines to add to the subgraph body (with-block use).

See the usage examples in the User Guide.

Note

If the name of the subgraph begins with 'cluster' (all lowercase) the layout engine will treat it as a special cluster subgraph.

view(filename=None, directory=None, cleanup=False)

Save the source to file, open the rendered result in a viewer.

Parameters:
  • filename – Filename for saving the source (defaults to name + '.gv')
  • directory – (Sub)directory for source saving and rendering.
  • cleanup (bool) – Delete the source file after rendering.
Returns:

The (possibly relative) path of the rendered file.
Raises:
  • graphviz.ExecutableNotFound – If the Graphviz executable is not found.
  • subprocess.CalledProcessError – If the exit status is non-zero.
  • RuntimeError – If opening the viewer is not supported.

Short-cut method for calling render() with view=True.

Digraph

class graphviz.Digraph(name=None, comment=None, filename=None, directory=None, format=None, engine=None, encoding='utf-8', graph_attr=None, node_attr=None, edge_attr=None, body=None, strict=False)

Directed graph source code in the DOT language.

Parameters:
  • name – Graph name used in the source code.
  • comment – Comment added to the first line of the source.
  • filename – Filename for saving the source (defaults to name + '.gv').
  • directory – (Sub)directory for source saving and rendering.
  • format – Rendering output format ('pdf', 'png', …).
  • engine – Layout command used ('dot', 'neato', …).
  • encoding – Encoding for saving the source.
  • graph_attr – Mapping of (attribute, value) pairs for the graph.
  • node_attr – Mapping of (attribute, value) pairs set for all nodes.
  • edge_attr – Mapping of (attribute, value) pairs set for all edges.
  • body – Iterable of verbatim lines to add to the graph body.
  • strict (bool) – Rendering should merge multi-edges.

Note

All parameters are optional and can be changed under their corresponding attribute name after instance creation.

attr(kw=None, _attributes=None, **attrs)

Add a general or graph/node/edge attribute statement.

Parameters:
  • kw – Attributes target (None or 'graph', 'node', 'edge').
  • attrs – Attributes to be set (must be strings, may be empty).

See the usage examples in the User Guide.

clear(keep_attrs=False)

Reset content to an empty body, clear graph/node/egde_attr mappings.

Parameters:keep_attrs (bool) – preserve graph/node/egde_attr mappings
copy()

Return a copied instance of the object.

Returns:An independent copy of the current object.
directed

True

edge(tail_name, head_name, label=None, _attributes=None, **attrs)

Create an edge between two nodes.

Parameters:
  • tail_name – Start node identifier.
  • head_name – End node identifier.
  • label – Caption to be displayed near the edge.
  • attrs – Any additional edge attributes (must be strings).
edges(tail_head_iter)

Create a bunch of edges.

Parameters:tail_head_iter – Iterable of (tail_name, head_name) pairs.
encoding

The encoding for the saved source file.

engine

The layout commmand used for rendering ('dot', 'neato', …).

format

The output format used for rendering ('pdf', 'png', …).

node(name, label=None, _attributes=None, **attrs)

Create a node.

Parameters:
  • name – Unique identifier for the node inside the source.
  • label – Caption to be displayed (defaults to the node name).
  • attrs – Any additional node attributes (must be strings).
pipe(format=None, renderer=None, formatter=None)

Return the source piped through the Graphviz layout command.

Parameters:
  • format – The output format used for rendering ('pdf', 'png', etc.).
  • renderer – The output renderer used for rendering ('cairo', 'gd', …).
  • formatter – The output formatter used for rendering ('cairo', 'gd', …).
Returns:

Binary (encoded) stdout of the layout command.
Raises:
render(filename=None, directory=None, view=False, cleanup=False, format=None, renderer=None, formatter=None)

Save the source to file and render with the Graphviz engine.

Parameters:
  • filename – Filename for saving the source (defaults to name + '.gv')
  • directory – (Sub)directory for source saving and rendering.
  • view (bool) – Open the rendered result with the default application.
  • cleanup (bool) – Delete the source file after rendering.
  • format – The output format used for rendering ('pdf', 'png', etc.).
  • renderer – The output renderer used for rendering ('cairo', 'gd', …).
  • formatter – The output formatter used for rendering ('cairo', 'gd', …).
Returns:

The (possibly relative) path of the rendered file.
Raises:
  • ValueError – If format, renderer, or formatter are not known.
  • graphviz.RequiredArgumentError – If formatter is given but renderer is None.
  • graphviz.ExecutableNotFound – If the Graphviz executable is not found.
  • subprocess.CalledProcessError – If the exit status is non-zero.
  • RuntimeError – If viewer opening is requested but not supported.
save(filename=None, directory=None)

Save the DOT source to file. Ensure the file ends with a newline.

Parameters:
  • filename – Filename for saving the source (defaults to name + '.gv')
  • directory – (Sub)directory for source saving and rendering.
Returns:

The (possibly relative) path of the saved source file.
source

The DOT source code as string.

subgraph(graph=None, name=None, comment=None, graph_attr=None, node_attr=None, edge_attr=None, body=None)

Add the current content of the given sole graph argument as subgraph or return a context manager returning a new graph instance created with the given (name, comment, etc.) arguments whose content is added as subgraph when leaving the context manager’s with-block.

Parameters:
  • graph – An instance of the same kind (Graph, Digraph) as the current graph (sole argument in non-with-block use).
  • name – Subgraph name (with-block use).
  • comment – Subgraph comment (with-block use).
  • graph_attr – Subgraph-level attribute-value mapping (with-block use).
  • node_attr – Node-level attribute-value mapping (with-block use).
  • edge_attr – Edge-level attribute-value mapping (with-block use).
  • body – Verbatim lines to add to the subgraph body (with-block use).

See the usage examples in the User Guide.

Note

If the name of the subgraph begins with 'cluster' (all lowercase) the layout engine will treat it as a special cluster subgraph.

view(filename=None, directory=None, cleanup=False)

Save the source to file, open the rendered result in a viewer.

Parameters:
  • filename – Filename for saving the source (defaults to name + '.gv')
  • directory – (Sub)directory for source saving and rendering.
  • cleanup (bool) – Delete the source file after rendering.
Returns:

The (possibly relative) path of the rendered file.
Raises:
  • graphviz.ExecutableNotFound – If the Graphviz executable is not found.
  • subprocess.CalledProcessError – If the exit status is non-zero.
  • RuntimeError – If opening the viewer is not supported.

Short-cut method for calling render() with view=True.

Source

class graphviz.Source(source, filename=None, directory=None, format=None, engine=None, encoding='utf-8')

Verbatim DOT source code string to be rendered by Graphviz.

Parameters:
  • source – The verbatim DOT source code string.
  • filename – Filename for saving the source (defaults to 'Source.gv').
  • directory – (Sub)directory for source saving and rendering.
  • format – Rendering output format ('pdf', 'png', …).
  • engine – Layout command used ('dot', 'neato', …).
  • encoding – Encoding for saving the source.

Note

All parameters except source are optional. All of them can be changed under their corresponding attribute name after instance creation.

copy()

Return a copied instance of the object.

Returns:An independent copy of the current object.
encoding

The encoding for the saved source file.

engine

The layout commmand used for rendering ('dot', 'neato', …).

format

The output format used for rendering ('pdf', 'png', …).

classmethod from_file(filename, directory=None, format=None, engine=None, encoding='utf-8')

Return an instance with the source string read from the given file.

Parameters:
  • filename – Filename for loading/saving the source.
  • directory – (Sub)directory for source loading/saving and rendering.
  • format – Rendering output format ('pdf', 'png', …).
  • engine – Layout command used ('dot', 'neato', …).
  • encoding – Encoding for loading/saving the source.
pipe(format=None, renderer=None, formatter=None)

Return the source piped through the Graphviz layout command.

Parameters:
  • format – The output format used for rendering ('pdf', 'png', etc.).
  • renderer – The output renderer used for rendering ('cairo', 'gd', …).
  • formatter – The output formatter used for rendering ('cairo', 'gd', …).
Returns:

Binary (encoded) stdout of the layout command.
Raises:
render(filename=None, directory=None, view=False, cleanup=False, format=None, renderer=None, formatter=None)

Save the source to file and render with the Graphviz engine.

Parameters:
  • filename – Filename for saving the source (defaults to name + '.gv')
  • directory – (Sub)directory for source saving and rendering.
  • view (bool) – Open the rendered result with the default application.
  • cleanup (bool) – Delete the source file after rendering.
  • format – The output format used for rendering ('pdf', 'png', etc.).
  • renderer – The output renderer used for rendering ('cairo', 'gd', …).
  • formatter – The output formatter used for rendering ('cairo', 'gd', …).
Returns:

The (possibly relative) path of the rendered file.
Raises:
  • ValueError – If format, renderer, or formatter are not known.
  • graphviz.RequiredArgumentError – If formatter is given but renderer is None.
  • graphviz.ExecutableNotFound – If the Graphviz executable is not found.
  • subprocess.CalledProcessError – If the exit status is non-zero.
  • RuntimeError – If viewer opening is requested but not supported.
save(filename=None, directory=None)

Save the DOT source to file. Ensure the file ends with a newline.

Parameters:
  • filename – Filename for saving the source (defaults to name + '.gv')
  • directory – (Sub)directory for source saving and rendering.
Returns:

The (possibly relative) path of the saved source file.
source

The verbatim DOT source code string.

view(filename=None, directory=None, cleanup=False)

Save the source to file, open the rendered result in a viewer.

Parameters:
  • filename – Filename for saving the source (defaults to name + '.gv')
  • directory – (Sub)directory for source saving and rendering.
  • cleanup (bool) – Delete the source file after rendering.
Returns:

The (possibly relative) path of the rendered file.
Raises:
  • graphviz.ExecutableNotFound – If the Graphviz executable is not found.
  • subprocess.CalledProcessError – If the exit status is non-zero.
  • RuntimeError – If opening the viewer is not supported.

Short-cut method for calling render() with view=True.

Low-level functions

The functions in this section are provided to work directly with existing files and strings instead of using the object-oriented DOT creation methods documented above.

graphviz.render(engine, format, filepath, renderer=None, formatter=None, quiet=False)

Render file with Graphviz engine into format, return result filename.

Parameters:
  • engine – The layout commmand used for rendering ('dot', 'neato', …).
  • format – The output format used for rendering ('pdf', 'png', …).
  • filepath – Path to the DOT source file to render.
  • renderer – The output renderer used for rendering ('cairo', 'gd', …).
  • formatter – The output formatter used for rendering ('cairo', 'gd', …).
  • quiet (bool) – Suppress stderr output.
Returns:

The (possibly relative) path of the rendered file.
Raises:
  • ValueError – If engine, format, renderer, or formatter are not known.
  • graphviz.RequiredArgumentError – If formatter is given but renderer is None.
  • graphviz.ExecutableNotFound – If the Graphviz executable is not found.
  • subprocess.CalledProcessError – If the exit status is non-zero.
graphviz.pipe(engine, format, data, renderer=None, formatter=None, quiet=False)

Return data piped through Graphviz engine into format.

Parameters:
  • engine – The layout commmand used for rendering ('dot', 'neato', …).
  • format – The output format used for rendering ('pdf', 'png', …).
  • data – The binary (encoded) DOT source string to render.
  • renderer – The output renderer used for rendering ('cairo', 'gd', …).
  • formatter – The output formatter used for rendering ('cairo', 'gd', …).
  • quiet (bool) – Suppress stderr output.
Returns:

Binary (encoded) stdout of the layout command.
Raises:
  • ValueError – If engine, format, renderer, or formatter are not known.
  • graphviz.RequiredArgumentError – If formatter is given but renderer is None.
  • graphviz.ExecutableNotFound – If the Graphviz executable is not found.
  • subprocess.CalledProcessError – If the exit status is non-zero.
graphviz.view(filepath)

Open filepath with its default viewing application (platform-specific).

Parameters:filepath – Path to the file to open in viewer.
Raises:RuntimeError – If the current platform is not supported.

Other

graphviz.ExecutableNotFound

Exception raised if the Graphviz executable is not found.

graphviz.RequiredArgumentError

Exception raised if a required argument is missing.

graphviz.version()

Return the version number tuple from the stderr output of dot -V.

Returns:

Two or three int version tuple.
Raises:
  • graphviz.ExecutableNotFound – If the Graphviz executable is not found.
  • subprocess.CalledProcessError – If the exit status is non-zero.
  • RuntimmeError – If the output cannot be parsed into a version number.
graphviz.nohtml(s)

Return copy of s that will not treat '<...>' as DOT HTML string in quoting.

Parameters:s – String in which leading '<' and trailing '>' should be treated as literal.
Raises:TypeError – If s is not a str on Python 3, or a str/unicode on Python 2. 
>>> quote('<>-*-<>')
'<>-*-<>'

>>> quote(nohtml('<>-*-<>'))
'"<>-*-<>"'

Manually maintained whitelists (see https://graphviz.gitlab.io/_pages/pdf/dot.1.pdf, http://www.graphviz.org/doc/info/output.html, and dot -T: output):

graphviz.ENGINES

Set of known layout commands used for rendering ('dot', 'neato', …)

graphviz.FORMATS

Set of known output formats for rendering ('pdf', 'png', …)

graphviz.RENDERERS

Set of known output formatters for rendering ('cairo', 'gd', …)

graphviz.FORMATTERS

Set of known output renderers for rendering ('cairo', 'gd', …)