installation instructions

Installing using Docker

The most hands-off and OS-agnostic way to install graph-tool is using Docker. If you have Docker installed, this can be done simply by running:

docker pull tiagopeixoto/graph-tool

This will download a Docker image based on Arch GNU/Linux, that contains graph-tool, and can be run in any modern GNU/Linux distribution, MacOS X and Windows. It contains some other useful Python packages, such as matplotlib, Pandas, IPython and Jupyter.

Interactive sessions

After the image is pulled, you can start an interactive python shell in the container by running:

docker run -it -u user -w /home/user tiagopeixoto/graph-tool ipython

which will give you a Python 3 environment with graph-tool installed:

Python 3.6.5 (default, May 11 2018, 04:00:52) 
Type 'copyright', 'credits' or 'license' for more information
IPython 6.3.1 -- An enhanced Interactive Python. Type '?' for help.

In [1]: from graph_tool.all import *
In [2]:

Interactive visualizations

If you want to use interactive visualization from within docker, you have first to enable local connections to the X server:

xhost +local:

and then run the container with

docker run -ti -u user -w /home/user --rm -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix tiagopeixoto/graph-tool ipython

Jupyter notebooks

To run jupyter notebooks from inside the docker image, you need to forward the necessary ports to the container, so that your native browser can connect to it at http://localhost:8888/. You need first to start an interactive shell session

docker run -p 8888:8888 -p 6006:6006 -it -u user -w /home/user tiagopeixoto/graph-tool bash

and then start the notebook server

[user@c20b92b8c4bf ~]$ jupyter notebook --ip 0.0.0.0

Do not forget to connect to http://localhost:8888/ instead of http://0.0.0.0:8888/, otherwise the connection to the kernel will not work!

(MacOS and Windows users still need to bind the above ports in the VM, as described here)

Native installation

Python modules are usually very easy to install, typically requiring nothing more that pip install <package> for basically any operating system. For graph-tool, however, the situation is different. This is because, in reality, graph-tool is a C++ library wrapped in Python, and it has many C++ dependencies such as Boost, CGAL and expat, which are not installable via Python-only package management systems such as pip. Because the module lives between the C++ and Python worlds, its installation is done more like a C++ library rather than a typical python module. This means it inherits some of the complexities common of the C++ world that some Python users do not expect.

The easiest way to get going is to use a package manager, for which the installation is fairly straightforward. This is the case for some GNU/Linux distributions (Arch, Gentoo, Debian & Ubuntu) as well as for MacOS users using either Macports or Homebrew. It is also possible to install it via anaconda for both GNU/Linux and MacOS, through conda-forge.

Alternatively, graph-tool can be installed from source, by manual compilation. The module uses the standard GNU build system for this (i.e. ./configure; make; make install), and users wishing to go on this route are recommended to familiarize themselves with it. Basic instructions are given below, and an in-depth resource is the Autotools Mythbuster.

Installation via package managers

GNU/Linux

Arch

Packages for Arch are available in the Arch User Repository. You can install it with pikaur:

pikaur -S python-graph-tool

Gentoo

An ebuild for graph-tool is included in the default Gentoo repository. Just do

emerge graph-tool

to install it.

Debian & Ubuntu

For Debian or Ubuntu, add the following line to your /etc/apt/sources.list,

deb [ arch=amd64 ] https://downloads.skewed.de/apt DISTRIBUTION main

where DISTRIBUTION can be any one of

bullseye, buster, sid, bionic, eoan, focal, groovy

You should then download the public key 612DEFB798507F25 to verify the packages, with the command:

apt-key adv --keyserver keys.openpgp.org --recv-key 612DEFB798507F25

After running apt-get update, the package can be installed with

apt-get install python3-graph-tool

MacOS X

Homebrew

With Homebrew the installation is also straightforward, since a formula for it is included in the main repository:

brew install graph-tool

Note that since current versions of Homebrew, pre-compiled binaries ("bottles") of graph-tool are available!

If you encounter an error installing graph-tool via Homebrew, please file a bug report to that project directly, not graph-tool: https://github.com/Homebrew/homebrew-core/issues

Macports

A portfile is available for installation in MacOS X systems with Macports. It is included in the standard macports list. Just run the following command to install it:

port install py-graph-tool

If you encounter an error installing graph-tool via Macports, please file a bug report to that project directly, not graph-tool: https://trac.macports.org/wiki/Tickets

Conda

It's possible to install graph-tool using the Conda package manager for both GNU/Linux and MacOS, via conda-forge. The packages are binary, so no compilation is necessary. This mode of installation is particularly useful when a system-wide installation is not possible due to lack of permissions, e.g. in HPC environments, since conda allows for unprivileged installations in a home directory.

The easiest way to install graph-tool is to create a new environment and install it there:

conda create --name gt -c conda-forge graph-tool
conda activate gt

After that, install additional packages to the environment as needed:

conda install -n gt -c conda-forge ipython jupyter

You can also install graph-tool to a pre-existing environment with the following command, but the solver is likely to fail (or hang) if your environment already contains many packages already, whose dependencies may conflict with the graph-tool dependencies. This is particularly likely if your environment contains packages from the official Anaconda distribution, rather than the conda-forge distribution.

conda install -c conda-forge graph-tool

Note: Rather than specifying -c conda-forge on every command, you can add conda-forge to your channels with:

conda config --add channels conda-forge

It is possible to list all of the versions of graph-tool available for your platform with:

conda search graph-tool --channel conda-forge

If experiencing problems with the conda package, please open an issue at the conda-forge github page.

Windows

Fully native installation on windows is not supported, but two viable options are either to use Docker (see here for instructions), or the Ubuntu userspace for windows (more information here and here), which allows the native Ubuntu packages to be installed as described above.

Manual compilation

Graph-tool was tested extensively only on GNU/Linux and MacOS X systems, but should also be usable on other systems where the below requirements are met.

Generic instructions

Having installed the above dependencies (which can be done either manually, or preferably via a package manager), the module can be compiled in the usual way:

$ ./configure
$ make

After compilation, the module can be installed in the default Python module directory by running:

$ make install

The above will install the library in the standard directories, and usually the final step requires root privileges.

Deviations from the standard directories will require that we inform the configure script in specific ways. This is done via configuration options or environment variables passed to the script. The most important ones are listed below:

Options to the `configure` script

--prefix=DIR: This sets the general installation prefix. If left unspecified, this defaults to DIR=/usr/local. Note that this is used to install only peripheral parts of the library, such as README and pkgconfig files. The location of the module itself is specified with the following option.
--with-python-module-path=DIR: This sets the location where the Python module will be installed. If left unspecified, this will be automatically determined using the Python interpreter. The default values may be something like DIR=/usr/lib/python3.6/site-packages, but this varies between OSs, virtualenvs, etc.
--with-boost-<libname>=NAME: The Boost libraries are installed with different names across OSs. The configure script tries to guess the names using common patterns, but this can fail. With this option, the user can specify the correct name (either the entire library name or just a suffix). For example, if the boost-python library is name libboost-python-mt-gcc6-py36-foobar, this can be passed to configure as --with-boost-python=-mt-gcc6-py36-foobar.

Environment variables

The configure script will consult some shell environment variables that will affect its configuration.

CXX: If defined, this variable should point to C++ compiler that will be used.
PYTHON: If defined, this variable should point to the Python interpreter that will be used.
CPPFLAGS: If defined, this variable will be used to pass extra flags to the C++ preprocessor (e.g. include flags of the form -I/some/path)
CXXFLAGS : If defined, this variable will be used to pass extra flags to the C++ compiler (e.g. debugging and optimization options, -O0 -g)
LDFLAGS: If defined, this variable will be used to pass extra flags to the shared object linker (e.g. paths to search for libraries, -L/some/path)

Below are some examples of using the above to achieve some common installation goals.

Installing in a specific location (e.g. in a home directory)

The library can be installed in non-standard locations. For example, the usual convention of installing local programs in the .local subdirectory of a user's home can be achieved by:

$ ./configure --prefix=$HOME/.local --with-python-module-path=$HOME/.local/lib/python3.6/site-packages
$ make install

After the library has been installed, we need to make sure that the Python interpreter knows where to find it. In modern OSs, the above should already be in the interpreter's path. But otherwise (or in case some other path is being used), we need to modify the PYTHONPATH environment variable

$ export PYTHONPATH="$PYTHONPATH:$HOME/.local/lib/python3.6/site-packages"

Dependencies installed in a nonstandard directory

If any of the dependencies have been installed in a nonstandard directory, we need to pass this information to the configure script. Suppose again these have been installed in the $HOME/.local directory. In this case we need

$ ./configure CPPFLAGS="-I$HOME/.local/include" LDFLAGS="-L$HOME/.local/lib -Wl,-rpath=$HOME/.local/lib"
$ make install

(typically, in such cases we also want to install the library itself in the home directory; for this we need to combine with the options in the previous section.)

Installing in a virtualenv

To install graph-tool in a virtualenv we need to activate it before running configure

$ cd my_project
$ source venv/bin/activate
$ cd graph-tool-X.XX
$ ./configure --prefix=$HOME/.local
$ make install

The --prefix is necessary only so that non-python-related parts are installed in the correct place.

Important: The boost-python dependency must be compiled against the same Python version that is used in the virtualenv.

Troubleshooting

If errors occur when running configure, look inside the config.log file for information on why the tests failed. Do not forget to include the contents of this file when reporting problems.

Memory requirements for compilation

Graph-tool requires relatively large amounts of RAM (~ 3 GB) during compilation, because it uses template metaprogramming extensively. Most compilers are still not not very well optimized for this, which means that even though the program is relatively small, it will still use up lots of RAM during compilation, specially if optimizations are used (and you do want to use them). Below you can see the memory usage during compilation using GCC 5.2.0 and clang 3.7.0, on a 64-bit GNU/Linux system with an Intel(R) Core(TM) i7-5500U CPU @ 2.40GHz.

GCC finishes under 80 minutes, and uses at most slightly below 3 GB. On the other hand, clang takes around 100 minutes, and has a memory use peak around 4 GB.

Parallel algorithms

graph-tool can run several of its algorithms in parallel. It makes use of OpenMP to do this, which provides a straightforward way of converting serial code into parallel code. OpenMP is an extension to the Fortran, C and C++ languages, which uses compiler directives to achieve automated code parallelization. Since it uses compiler directives (#pragma in C/C++), it maintains backwards compatibility with compilers that do not support OpenMP, and the code is then compiled cleanly as regular serial code. Thus, support for parallel code in graph-tool is quite optional. It is enabled by default, but if you wish to disable it, just pass the option --disable-openmp to the configure script.

Google's colaboratory

Colaboratory (also known as Colab) is a free Jupyter notebook environment that runs in the cloud and stores its notebooks on Google Drive. Since it's based on an Ubuntu system, we can install graph-tool on it using the instructions above. Please see here for a working Colab installation of graph-tool: https://colab.research.google.com/github/count0/colab-gt/blob/master/colab-gt.ipynb