Installing¶

Quick Install¶

Get PyGraphviz from the Python Package Index at http://pypi.python.org/pypi/pygraphviz

or install it with:

and an attempt will be made to find and install an appropriate version that matches your operating system and Python version.

You can install the development version (at github.com) with:

Providing path to graphviz¶

We tried our best to discover graphviz location automatically, but if you would like specify specific location for graphviz you may provide additrional parameters to specify graphviz location

include-path= path to graphviz include files library-path= path to graphviz library files

Installing from Source¶

You can install from source by downloading a source archive file (tar.gz or zip) or by checking out the source files from the Subversion repository.

Source Archive File¶

1. Download the source (tar.gz or zip file).
2. Unpack and change directory to pygraphviz-“version”
3. Run “python setup.py install” to build and install
4. (optional) Run “python setup_egg.py nosetests” to execute the tests

Github¶

Clone the pygraphviz repository

1. Change directory to “pygraphviz”
2. Run “python setup.py install” to build and install
3. (optional) Run “python setup_egg.py nosetests” to execute the tests

If you don’t have permission to install software on your system, you can install into another directory using the –user, –prefix, or –home flags to setup.py.

If you didn’t install in the standard Python site-packages directory you will need to set your PYTHONPATH variable to the alternate location. Seehttp://docs.python.org/2/install/index.html#search-path for further details.

Requirements¶

Python¶

PyGraphviz is tested and works with Python 2.7, 3.5, 3.6, and 3.7.

There are several other distributions that contain the key packages you need for scientific computing. See the following link for a list: http://scipy.org/install.html

GraphViz¶

To use PyGraphviz you need GraphViz version 2.16 or later. Some versions have known bugs that have been fixed; get the latest release available for best results.

Installing¶

Quick Install¶

Get PyGraphviz from the Python Package Index at http://pypi.python.org/pypi/pygraphviz

or install it with:

and an attempt will be made to find and install an appropriate version that matches your operating system and Python version.

You can install the development version (at github.com) with:

Get PyGraphviz from the Python Package Index at http://pypi.python.org/pypi/pygraphviz

or install it with:

and an attempt will be made to find and install an appropriate version that matches your operating system and Python version.

Providing path to graphviz¶

We tried our best to discover graphviz location automatically, but if you would like specify specific location for graphviz you may provide additrional parameters to specify graphviz location

include-path= path to graphviz include files library-path= path to graphviz library files

Installing from Source¶

You can install from source by downloading a source archive file (tar.gz or zip) or by checking out the source files from the Subversion repository.

Source Archive File¶

1. Download the source (tar.gz or zip file).
2. Unpack and change directory to pygraphviz-“version”
3. Run “python setup.py install” to build and install
4. (optional) Run “python setup_egg.py nosetests” to execute the tests

Github¶

Clone the pygraphviz repository

1. Change directory to “pygraphviz”
2. Run “python setup.py install” to build and install
3. (optional) Run “python setup_egg.py nosetests” to execute the tests

If you don’t have permission to install software on your system, you can install into another directory using the –user, –prefix, or –home flags to setup.py.

If you didn’t install in the standard Python site-packages directory you will need to set your PYTHONPATH variable to the alternate location. Seehttp://docs.python.org/2/install/index.html#search-path for further details.

Requirements¶

Python¶

PyGraphviz is tested and works with Python 2.7 and Python 3.4. It may work correctly with other Python 3.x versions.

The easiest way to get Python and most optional packages is to install the Enthought Python distribution “Canopy” https://www.enthought.com/products/canopy/

There are several other distributions that contain the key packages you need for scientific computing. See the following link for a list: http://scipy.org/install.html

Requirements¶

GraphViz¶

To use PyGraphviz you need GraphViz version 2.16 or later. Some versions have known bugs that have been fixed; get the latest release available for best results.

Installing¶

Quick Install¶

Get PyGraphviz from the Python Package Index at http://pypi.python.org/pypi/pygraphviz

or install it with:

and an attempt will be made to find and install an appropriate version that matches your operating system and Python version.

You can install the development version (at github.com) with:

Get PyGraphviz from the Python Package Index at http://pypi.python.org/pypi/pygraphviz

or install it with:

and an attempt will be made to find and install an appropriate version that matches your operating system and Python version.

Providing path to graphviz¶

We tried our best to discover graphviz location automatically, but if you would like specify specific location for graphviz you may provide additrional parameters to specify graphviz location

include-path= path to graphviz include files library-path= path to graphviz library files

Installing from Source¶

You can install from source by downloading a source archive file (tar.gz or zip) or by checking out the source files from the Subversion repository.

Source Archive File¶

1. Download the source (tar.gz or zip file).
2. Unpack and change directory to pygraphviz-“version”
3. Run “python setup.py install” to build and install
4. (optional) Run “python setup_egg.py nosetests” to execute the tests

Github¶

Clone the pygraphviz repository

1. Change directory to “pygraphviz”
2. Run “python setup.py install” to build and install
3. (optional) Run “python setup_egg.py nosetests” to execute the tests

If you don’t have permission to install software on your system, you can install into another directory using the –user, –prefix, or –home flags to setup.py.

If you didn’t install in the standard Python site-packages directory you will need to set your PYTHONPATH variable to the alternate location. Seehttp://docs.python.org/2/install/index.html#search-path for further details.

Requirements¶

Python¶

PyGraphviz is tested and works with Python 2.7 and Python 3.4. It may work correctly with other Python 3.x versions.

The easiest way to get Python and most optional packages is to install the Enthought Python distribution “Canopy” https://www.enthought.com/products/canopy/

There are several other distributions that contain the key packages you need for scientific computing. See the following link for a list: http://scipy.org/install.html

Requirements¶

GraphViz¶

To use PyGraphviz you need GraphViz version 2.16 or later. Some versions have known bugs that have been fixed; get the latest release available for best results.

User Guide¶

Installation¶

graphviz provides a simple pure-Python interface for the Graphviz graph-drawing software. It runs under Python 2.7 and 3.6+. To install it with pip run the following:

For a system-wide install, this typically requires administrator access. For an isolated install, you can run the same inside a virtualenv or a venv (Python 3 only).

After installing Graphviz, make sure that its bin/ subdirectory containing the layout commands for rendering graph descriptions ( dot , circo , neato , etc.) is on your systems’ path: On the command-line, dot -V should print the version of your Graphiz installation.

Windows users might want to check the status of known issues (gvedit.exe, sfdp, commands) and consider trying an older archived version as a workaround (e.g. graphviz-2.38.msi).

Basic usage¶

The graphviz module provides two classes: Graph and Digraph . They create graph descriptions in the DOT language for undirected and directed graphs respectively. They have the same API .

Create a graph by instantiating a new Graph or Digraph object:

Their constructors allow to set the graph’s name , the filename for the DOT source and the rendered graph, a comment for the first source code line, etc.

Add nodes and edges to the graph object using its node() and edge() — or edges() -methods:

The node() -method takes a name identifier as first argument and an optional label . The edge() -method takes the names of start node and end node, while edges() takes an iterable of name pairs. Keyword arguments are turned into (node and edge) attributes (see Graphviz docs on available attributes).

Check the generated source code:

Use the render() -method to save the source code and render it with the default layout program ( dot , see below for using other layout commands).

Passing view=True will automatically open the resulting (PDF, PNG, SVG, etc.) file with your system’s default viewer application for the file type.

Formats¶

To use a different output file format than the default PDF, use the format argument when creating your Graph or Digraph object:

You can also change the format attribute on an existing graph object:

Piped output¶

To directly access the results from the Graphviz rendering command (e.g. dot ) as binary data string from within Python instead of writing to a file, use the pipe() -method of your Graph or Digraph object:

Note that pipe() returns the raw stdout from the rendering command ( str on Python 2, bytes on Python 3): When piping into plain-text formats like ‘svg’ or ‘plain’ , you usually want to decode the return value as shown above.

The output for pipe() is buffered in memory, so do not use this method if the data size is large.

Jupyter notebooks¶

Graph and Digraph objects have a _repr_svg_() -method so they can be rendered and displayed directly inside a Jupyter notebook. For an example, check the examples/graphviz-notebook.ipynb file in the source repository/distribution (or the same rendered within nbviewer).

This also allows direct displaying within the Jupyter Qt Console (e.g. the one inside Spyder IDE):

Styling¶

Use the graph_attr , node_attr , and edge_attr arguments to change the default appearance of your graph, nodes, and edges.

After creation, they can be edited on the graph object:

Attributes¶

To directly add attritbute statements (affecting all following graph, node, or edge items within the same (sub-)graph), use the attr() -method with the target as first argument:

By omitting its first argument, you can use it to set arbitrary attributes as key-value pairs targeting the current (sub-)graph (e.g. for rankdir , label , or setting rank=’same’ within a subgraph context, example ):

Node ports & compass¶

The edge() — and edges() -methods use the colon-separated format node[:port[:compass]] for tail and head nodes. This allows to specify an optional node port plus an optional compass point the edge should aim at for the given tail or head node ( example ).

As colons are used to indicate port and compass , node names with literal colon(s) ( : ) are not supported. Note that there is no such restriction for the label argument, so you can work around by choosing a colon-free name together with the wanted label :

Backslash escapes¶

The Graphviz layout engine supports a number of escape sequences such as \n , \l , \r (for multi-line labels: centered, left-justified, right-justified) and \N , \G , \L (expanded to the current node name, graph name, object label). To be able to use them from this library (e.g. for labels), strings with backslashes are passed on as is. This means that literal backslashes need to be escaped (doubled) by the user. As the backslash is also special in Python string literals, a second level of doubling is needed (e.g. label=’\\\\’ ). This kind of doubling can be avoided by using raw string literals ( r’. ‘ ) instead (same solution as proposed for the stdlib re module):

To disable any special character meaning in a string (e.g. from user input to be rendered literally), use the escape() function (cf. the re.escape() function):

To prevent breaking the internal quoting mechanism, the special meaning of \» as a backslash-escaped quote has been disabled since version 0.14 . E.g. both label='»‘ and label=’\\»‘ now produce the same DOT source [label=»\»»] (a label that renders as a literal quote).

Quoting and HTML-like labels¶

The graph-building methods of Graph and Digraph objects automatically take care of quoting (and escaping quotes) where needed (whitespace, keywords, double quotes, etc.):

If a string starts with ‘ and ends with ‘>’ , it is passed on as is, without quoting/escaping: The content between the angle brackets is treated by the engine as special HTML string that can be used for HTML-like labels:

For strings that should literally begin with ‘ and end with ‘>’ , use the nohtml() function to disable the special meaning of angled parenthesis and apply normal quoting/escaping (before 0.8.2 , the only workaround was to add leading or trailing space, e.g. label=’ <>‘ ):

Subgraphs & clusters¶

Graph and Digraph objects have a subgraph() -method for adding a subgraph to an instance.

There are two ways to use it: Either with a ready-made graph object of the same kind as the only argument (whose content is added as a subgraph) or omitting the graph argument (returning a context manager for defining the subgraph content more elegantly within a with -block).

First usage option, with graph as the only argument:

Second usage, with a with -block (omitting the graph argument):

Both produce the same result:

If the name of a subgraph begins with ‘cluster’ (all lowercase) the layout engine will treat it as a special cluster subgraph ( example ). Also see the Subgraphs and Clusters section of the DOT language documentation.

When subgraph() is used as a context manager, the new graph instance is created with strict=None and the parent graph’s values for directory , format , engine , and encoding . Note that these attributes are only relevant when rendering the subgraph independently (i.e. as a stand-alone graph) from within the with -block:

Engines¶

To use a different layout command than the default dot when rendering your graph, use the engine argument when creating your graph.

You can also change the engine attribute of an existing instance:

Unflatten¶

To prepocess the DOT source of a Graph or Digraph with the unflatten preprocessor (PDF), use the unflatten() -method.

unflatten is used to improve the aspect ratio of graphs having many leaves or disconnected nodes.

The method returns a Source object that you can render() , view() , etc. with the same API (minus modification, see details below).

Custom DOT statements¶

To add arbitrary statements to the created DOT source, use the body attribute of the Graph or Digraph object. It holds the verbatim list of lines to be written to the source file. Use its append() — or extend() -method:

Note that you might need to correctly quote/escape identifiers and strings containing whitespace or other special characters when using this method.

Using raw DOT¶

To render a ready-made DOT source code string (instead of assembling one with the higher-level interface of Graph or Digraph ), create a Source object holding your DOT string:

Use the render() -method to save and render it:

Apart from the missing editing methods, Source objects are the same as the higher-level graph objects ( pipe() -method, format , engine , Jupyter notebook repr, etc.), see above.

Existing files¶

To directly render an existing DOT source file (e.g. created with other tools), you can use the graphviz.render() function.

To directly display the graph of an existing DOT source file inside a Jupyter notebook or Qt Console, you can use the Source.from_file() -classmethod (alternate constructor):

Note that if you call render() or view() on the returned Source object, it will still save() as usual (i.e. write the content read into source back into the file). You can use graphviz.render() and graphiz.view() to directly work on files in case you need to avoid this round-trip.

Integration with viewers¶

On platforms such as Windows, viewer programs opened by rendering with view=True or the view() -method might lock the (PDF, PNG, etc.) file for as long as the viewer is open (blocking re-rendering it with a Permission denied error). You can use the mktemp() function from the stdlib tempfile module to render to a different file for each invocation to avoid needing to close the viewer window each time within such an incremental workflow (and also preserve its intermediate steps):

Other options are viewers that support live updates or using the Jupyter notebook or Qt Console to display the current version of the rendered graph in repeated add/render/view cycles.

© Copyright 2013-2020, Sebastian Bank Revision 54b4eecd .