Installing igraph

Compiling igraph from source

You might want to compile igraph to test a recently added feature ahead of release or to install igraph on architectures not covered by our continuous development pipeline.

Note

In all cases, the Python interface needs to be compiled against a matching version of the igraph core C library. If you used git to check out the source tree, git was probably smart enough to check out the matching version of igraph’s C core as a submodule into vendor/source/igraph. You can use git submodule update --init --recursive to check out the submodule manually, or you can run git submodule status to print the exact revision of igraph’s C core that should be used with the Python interface.

Compiling using pip

If you want the development version of igraph, call:

$ pip install git+https://github.com/igraph/python-igraph

pip is smart enough to download the sources from Github, initialize the submodule for the igraph C core, compile it, and then compile the Python interface against it and install it. As above, a virtual environment is a commonly used sandbox to test experimental packages.

If you want the latest release from PyPI but prefer to (or have to) install from source, call:

$ pip install --no-binary ':all:' igraph

Note

If there is no binary for your system anyway, you can just try without the --no-binary option and obtain the same result.

Compiling step by step

This section should be rarely used in practice but explains how to compile and install igraph step by step from a local checkout, i.e. _not_ relying on pip to fetch the sources. (You would still need pip to install from source, or a PEP 517-compliant build frontend like build to build an installable Python wheel.

First, obtain the bleeding-edge source code from Github:

$ git clone https://github.com/igraph/python-igraph.git

or download a recent release from PyPI or from the Github releases page. Decompress the archive if needed.

Second, go into the folder:

$ cd python-igraph

(it might have a slightly different name depending on the release).

Third, if you cloned the source from Github, initialize the git submodule for the igraph C core:

$ git submodule update --init

Note

If you prefer to compile and link igraph against an existing igraph C core, for instance the one you installed with your package manager, you can skip the git submodule initialization step. If you downloaded a tarball, you also need to remove the vendor/source/igraph folder because the setup script will look for the vendored igraph copy first. However, a particular version of the Python interface is guaranteed to work only with the version of the C core that is bundled with it (or with the revision that the git submodule points to).

Fourth, call pip to compile and install the package from source:

$ pip install .

Alternatively, you can call build or another PEP 517-compliant build frontend to build an installable Python wheel. Here we use pipx to invoke build in a separate virtualenv:

$ pipx run build

Testing your installation

Use tox or another standard test runner tool to run all the unit tests. Here we use pipx <https://pypa.github.io/pipx/>`_ to invoke tox:

$ pipx run tox

You can also call tox directly from the root folder of the igraph source tree if you already installed tox system-wide:

$ tox

Troubleshooting

Q: I am trying to install igraph on Windows but am getting DLL import errors

A: The most common reason for this error is that you do not have the Visual C++ Redistributable library installed on your machine. Python’s own installer is supposed to install it, but in case it was not installed on your system, you can download it from Microsoft.

Q: I am trying to use igraph but get errors about something called Cairo

A: igraph by default uses a third-party called Cairo for plotting. If Cairo is not installed on your computer, you might get an import error. This error is most commonly encountered on Windows machines.

There are two solutions to this problem: installing Cairo or, if you are using a recent versions of igraph, switching to the matplotlib plotting backend.

1. Install Cairo: As explained here, you need to install Cairo headers using your package manager (Linux) or homebrew (macOS) and then:

$ pip install pycairo

The Cairo project does not provide pre-compiled binaries for Windows, but Christoph Gohlke maintains a site containing unofficial Windows binaries for several Python extension packages, including Cairo. Therefore, the easiest way to install Cairo on Windows along with its Python bindings is simply to download it from Christoph’s site. Make sure you use an installer that is suitable for your Windows platform (32-bit or 64-bit) and the version of Python you are using.

To check if Cairo is installed correctly on your system, run the following example:

>>> import igraph as ig
>>> g = ig.Graph.Famous("petersen")
>>> ig.plot(g)

If PyCairo was successfully installed, this will display a Petersen graph.

2. Switch to matplotlib: You can configure igraph to use matplotlib instead of Cairo. First, install it:

$ pip install matplotlib

To use matplotlib for a single plot, create a matplotlib.figure.Figure and matplotlib.axes.Axes beforehand (e.g. using matplotlib.pyplot.subplots()):

>>> import matplotlib.pyplot as plt
>>> import igraph as ig
>>> fig, ax = plt.subplots()
>>> g = ig.Graph.Famous("petersen")
>>> ig.plot(g, target=ax)
>>> plt.show()

To use matplotlib for a whole session/notebook:

>>> import matplotlib.pyplot as plt
>>> import igraph as ig
>>> ig.config["plotting.backend"] = "matplotlib"
>>> g = ig.Graph.Famous("petersen")
>>> ig.plot(g)
>>> plt.show()

To preserve this preference across sessions/notebooks, you can store it in the default configuration file used by igraph:

>>> import igraph as ig
>>> ig.config["plotting.backend"] = "matplotlib"
>>> ig.config.save()

From now on, igraph will default to matplotlib for plotting.