Installation instructions

Installing via Conda

Tip

Installation via conda, in particular miniforge, is recommended for the vast majority of users. If in doubt, try this method first!

The simplest way to install graph-tool is using the Conda package manager for both GNU/Linux and MacOS, via conda-forge. The packages are binary, so no compilation is necessary.

Tip

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
Note

If experiencing problems with the conda package, please open an issue at the conda-forge github page, instead of directly to the graph-tool project.

At this point you should have the package installed and ready to use! 🤘

Optimized binaries

The conda package will install binaries that are optimized for your specific CPU micro-architecture, including SIMD vectorization, in addition to having OpenMP enabled.

This in an advantage in comparison, for example, with the Debian/Ubuntu packages, that are compiled in a manner that is compatible with all micro-architectures, and therefore do not include more advanced optimizations.

Customizing your conda environment

Optionally, you may wish to install additional packages in the same environment as needed, for example:

conda install -n gt -c conda-forge ipython jupyter
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
Warning

You can also install graph-tool in a pre-existing environment with the following command,

conda install -c conda-forge graph-tool

however the solver is likely to fail (or hang) if your environment 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.

Much nicer alternatives to conda

There are alternatives to conda that make the installation even easier. One of them is mamba, which is a drop-in replacement for conda that is much faster and has a much more robust dependency computation framework.

Another particularly nice option is pixi, which uses conda environments and conda-forge packages, but is designed to encourage project-centric package management instead of monolithic environments, besides being much faster and giving nicer error messages.

Installation of pixi is trivial:

curl -fsSL https://pixi.sh/install.sh | bash
source ~/.bash_profile

You can then create a project and install graph-tool in it as follows:

# setup your project
mkdir my-project
cd my-project

# Create a conda environment just for this project.
pixi init
pixi add graph-tool

# Activate the environment for the current project (i.e. the one in this directory)
pixi shell

In this way you can have a separate environment for each project. This is highly recommended as an alternative to conda!

Installing using Docker

The most OS-agnostic way to install graph-tool is using Docker, for which an official image is available. 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 shell 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:

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

Running 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
Important

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!

Tip

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

Development snapshots

Continuous snapshots of the most current development version of graph-tool are available in the graph-tool-git docker repository. This repository is updated automatically after every commit is made to the upstream git repository.

Warning

The development version may contain known bugs! Prefer the stable releases whenever possible.

The development version can be installed simply by running:

docker pull tiagopeixoto/graph-tool-git

And following the same usage instructions as above.

Installing using Apptainer (née Singularity)

Apptainer (a.k.a. Singularity) is a virtualization platform similar to docker, but is simpler to use and does not require administration privileges — it can be run as a regular user in a shared environment. One of the main uses of Apptainer is to bring containers and reproducibility to scientific computing and the high-performance computing (HPC) systems. The idea is that you can setup your own up-to-date software stack in a container and use it to run jobs in your HPC cluster, which usually contains only outdated software, liberating you from depending on admins!

graph-tool can also be used with singularity via its docker images, which can be easily converted to Apptainer/singularity images. This is done with:

apptainer pull docker://tiagopeixoto/graph-tool

This will create an image file graph-tool_latest.sif, which you then can use, e.g. with:

apptainer exec graph-tool-git_latest.sif python3 -c "import graph_tool.all"

The development versions are available as well in the graph-tool-git repository.

Warning

The docker images contain a version of the glibc library which is compatible with Linux kernel versions as old as 4, but not older. This might be a problem on (very old) CentOS installations.

Google Colab

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.

Testing the git version

If you want to test the current development version of graph-tool you can do this easily using this colab notebook.

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. As discussed before, 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.

Arch GNU/Linux

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

pikaur -S python-graph-tool
Optimized binaries

If you install graph-tool via AUR, it will be compiled and optimized for your specific CPU micro-architecture, including SIMD vectorization, in addition to having OpenMP enabled.

This in an advantage in comparison, for example, with the Debian/Ubuntu packages, that are compiled in a manner that is compatible with all micro-architectures, and therefore do not include more advanced optimizations.

Gentoo GNU/Linux

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

emerge graph-tool

to install it.

Debian & Ubuntu GNU/Linux

Tip

It can take some time for the newest graph-tool version to make to the official Debian and Ubuntu repositories. If you don’t want to wait, consider using the upstream repository.

Official Debian packages

There is a package on the official Debian repository called python3-graph-tool. Just do

apt-get install python3-graph-tool

to install it.

The latest versions are typically available only in the unstable repository. They can be installed in a stable release (currently bookworm) via backports, as follows:

apt-get -t bookworm-backports install graph-tool

Official Ubuntu packages

Official Ubuntu packages are available for newer releases (see list here). Just do

apt-get install python3-graph-tool

to install it.

Upstream repository

We also provide an upstream repository for graph-tool. This is useful for other Debian or Ubuntu releases not covered by the official repositories, or if you want to install a newer version that has not yet made it there. New graph-tool versions are made available in the upstream repository almost immediately after release, while they can take some days to appear in the unstable Debian repository, and much longer on the other repositories. The upstream repository is the easiest way to remain on the bleeding edge.

When installing for the first time, the first step is to install the keyring package that allows signatures to be verified:

wget https://downloads.skewed.de/skewed-keyring/skewed-keyring_1.1_all_$(lsb_release -s -c).deb
dpkg -i skewed-keyring_1.1_all_$(lsb_release -s -c).deb

When updating the package, the above step is no longer necessary.

Secondly, you need to add the repository to your /etc/apt/sources.list.d directory:

echo "deb [signed-by=/usr/share/keyrings/skewed-keyring.gpg] https://downloads.skewed.de/apt $(lsb_release -s -c) main" > \
    /etc/apt/sources.list.d/skewed.list

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

apt-get install python3-graph-tool
Note

At this time, the supported Debian versions are:

bookworm, bullseye, buster, sid, trixie

and the folloing for Ubuntu:

focal, jammy, lunar, mantic, noble, oracular
Git snapshots

Packages are also available for development versions of graph-tool. They correspond to the current HEAD of the master branch of the git repository, and are build shortly after commits are made to it. To use these packages, you need to add the following line to your /etc/apt/sources.list,

echo "deb [trusted=yes] https://downloads.skewed.de/apt-git $(lsb_release -s -c) main" >> /etc/apt/sources.list.d/skewed.list

Note that both repositories are compatible, and can be installed side by side, and the newest version of the library will be selected correctly.

Warning

Please note that, unlike the stable releases, the git repository is unsigned, and this is why the “[trusted=yes]” parameter is needed above.

Fedora GNU/Linux

There’s a fedora package for graph-tool called python3-graph-tool. To install it, just run:

dnf install python3-graph-tool

MacOS X

Homebrew

Note

If you encounter an error installing graph-tool via Homebrew, please file a bug report to that project directly, not graph-tool.

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

brew install graph-tool
Note

Note that for current versions of Homebrew, pre-compiled binaries (“bottles”) of graph-tool are available!

Macports

Note

If you encounter an error installing graph-tool via Macports, please file a bug report to that project directly, not graph-tool.

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

Windows

To use graph-tool on windows, you need to first install Windows Subsystem for Linux (WSL) as described here.

Usually, this requires simply running the command below on the power shell:

wsl --install

and then rebooting. You will be asked to provide a username and password.

This will install an Ubuntu subsystem alongside your windows OS. You then can install graph-tool just like described in the Debian/Ubuntu section above, i.e. you should open the file

sudo nano /etc/apt/sources.list

and add the following line to the bottom:

deb https://downloads.skewed.de/apt jammy main
Warning

jammy is the current version of Ubuntu at the time of this writing, it should replaced with most current version, or with whatever version you happen to be using.

You should then add the signing key:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key 612DEFB798507F25

and update the package list:

sudo apt-get update

To enable all functionalities, the following extra packages need to be installed:

sudo apt-get install python3-cairo python3-gi-cairo python3-gi gnome pip
sudo pip install zstandard

Finally, the package itself can be installed via:

sudo apt-get install python3-graph-tool
Tip

If you want interactive visualization to work, follow the guide here.

Manual compilation

Warning

Manual compilation is generally considered more difficult than the methods above, which should be preferred by most users.

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
Tip

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 (#pragmain 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.

lglpv3
by Tiago P. Peixoto