- Installing using Docker
- Installation via package managers
- Manual compilation
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.
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
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 : 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 -e DISPLAY=$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
and then start the notebook server
[user@c20b92b8c4bf ~]$ jupyter notebook --ip 0.0.0.0
(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 is also possible to install it via anaconda for both GNU/Linux and MacOS, through conda-forge.
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
Packages for Arch are available in the Arch User Repository. You can install it with pikaur:
pikaur -S python-graph-tool
An ebuild for graph-tool is included in the default Gentoo repository. Just do
to install it.
Debian & Ubuntu
For Debian, add the following lines to your
deb http://downloads.skewed.de/apt/DISTRIBUTION DISTRIBUTION main deb-src http://downloads.skewed.de/apt/DISTRIBUTION DISTRIBUTION main
DISTRIBUTION can be any one of
bullseye, buster, sid
For Ubuntu, add the following lines
deb http://downloads.skewed.de/apt/DISTRIBUTION DISTRIBUTION universe deb-src http://downloads.skewed.de/apt/DISTRIBUTION DISTRIBUTION universe
DISTRIBUTION can be any one of
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
apt-get update, the package can be installed with
apt-get install python3-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 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
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 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 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.
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 Boost libraries, version 1.55 or above.
- Python version 3 or above.
- The expat XML library.
- The SciPy python module.
- The Numpy python module, version 1.7 or above.
- The CGAL C++ geometry library, version 3.5 or above.
- The sparsehash template library (optional, but recommended).
- The GTK+ 3, cairomm, pycairo and matplotlib libraries, used for graph drawing (optional).
- 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
--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
configurescript 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
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
CXXFLAGS: If defined, this variable will be used to pass extra flags to the C++ compiler (e.g. debugging and optimization options,
LDFLAGS: If defined, this variable will be used to pass extra flags to the shared object linker (e.g. paths to search for libraries,
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.)
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
--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 (
#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.