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.
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 informationIPython 6.3.1 -- An enhanced Interactive Python. Type '?' for help.In : from graph_tool.all import *In :
If you want to use interactive visualization from within docker, you have first to enable local connections to the X server:
and then run the container with
docker run -ti-u user -w /home/user --rm-eDISPLAY=$DISPLAY-v /tmp/.X11-unix:/tmp/.X11-unix tiagopeixoto/graph-tool ipython
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
(MacOS and Windows users still need to bind the above ports in the VM, as described here)
Modifying the docker image
If you are interested in modifying or extending the image, you can download the Dockerfile.
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's possible to install graph-tool using Anaconda for both GNU/Linux and MacOS, via conda-forge. The packages are binary, so no compilation is necessary. Just type:
conda install -c conda-forge graph-tool
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.
Fully native installation on windows is not supported, but two viable options are using Docker (see here for instructions), and using the Ubuntu userspace for windows (more information here and here), which allows the native Ubuntu packages to be installed as described above.
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.
A C++17 compiler (GCC version 7 or above, or clang version 5 or above).
The Graphviz packaged for graph drawing, with the python bindings enabled (optional, deprecated).
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.
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
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.)
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.
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.
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.