Repository files navigation

igraph is a library for creating and manipulating graphs.It is intended to be as powerful (ie. fast) as possible to enable theanalysis of large graphs.

This repository contains the source code to the Python interface ofigraph.

Since version 0.10.2, the documentation is hosted onreadthedocs. Earlier versions are documentedonour old website.

igraph is a collaborative work of many people from all around the world —see thelist of contributors here.

If you use igraph in your research, please cite

Csardi, G., & Nepusz, T. (2006). The igraph software package for complex network research. InterJournal, Complex Systems, 1695.

We aim to provide wheels on PyPI for most of the stock Python versions;typically at least the three most recent minor releases from Python 3.x.Therefore, running the following command should work without having to compileanything during installation:

pip install igraph

See details inInstalling Python Modules.

If you need to compile igraph from source for some reason, you need toinstall some dependencies first:

sudo apt install build-essential python-dev libxml2 libxml2-dev zlib1g-dev

and then run

pip install igraph

This should compile the C core of igraph as well as the Python extensionautomatically.

It is now also possible to compileigraph from source under Windows forPython 3.7 and later. Make sure that you have Microsoft Visual Studio 2015 orlater installed, and of course Python 3.7 or later. First extract the source toa suitable directory. If you launch the Developer command prompt and navigate tothe directory where you extracted the source code, you should be able to buildand install igraph usingpip install ., assuming that you havepipinstalled in your Python environment.

You may need to set the architecture that you are building on explicitly by setting the environment variable

set IGRAPH_CMAKE_EXTRA_ARGS=-A [arch]

where[arch] is eitherWin32 for 32-bit builds orx64 for 64-bit builds.Also, when building in MSYS2, you need to set theSETUPTOOLS_USE_DISTUTILSenvironment variable tostdlib; this is because MSYS2 uses a patched versionofdistutils that conflicts withsetuptools >= 60.0.

By default, GraphML is disabled, becauselibxml2 is not available on Windows inthe standard installation. You can installlibxml2 on Windows usingvcpkg. After installation ofvcpkg youcan installlibxml2 as follows

vcpkg.exe install libxml2:x64-windows-static-md

for 64-bit version (for 32-bit versions you can use thex86-windows-static-mdtriplet). You need to integratevcpkg in the build environment using

vcpkg.exe integrate install

This mentions that

CMake projects should use:-DCMAKE_TOOLCHAIN_FILE=[vcpkg build script]

which we will do next. In order to buildigraph correctly, you alsoneed to set some other environment variables before buildingigraph:

set IGRAPH_CMAKE_EXTRA_ARGS=-DVCPKG_TARGET_TRIPLET=x64-windows-static-md -DCMAKE_TOOLCHAIN_FILE=[vcpkg build script]set IGRAPH_EXTRA_LIBRARY_PATH=[vcpkg directory]/installed/x64-windows-static-md/lib/set IGRAPH_STATIC_EXTENSION=Trueset IGRAPH_EXTRA_LIBRARIES=libxml2,lzma,zlib,iconv,charsetset IGRAPH_EXTRA_DYNAMIC_LIBRARIES: wsock32,ws2_32

You can now build and installigraph again by simply runningpip install ..Please make sure to use a clean source tree, if you built previously withoutGraphML, it will not update the build.

The source code of the Python package includes the source code of the matchingigraph version that the Python interface should compile against. However, ifyou want to link the Python interface to a custom installation of the C corethat has already been compiled and installed on your system, you can ask ourbuild system to use the pre-compiled version. This option requires that yourcustom installation of igraph is discoverable withpkg-config. First, checkwhetherpkg-config can tell you the required compiler and linker flags forigraph:

pkg-config --cflags --libs igraph

Ifpkg-config responds with a set of compiler and linker flags and not anerror message, you are probably okay. You can then proceed with theinstallation using pip after setting the environment variable namedIGRAPH_USE_PKG_CONFIG to1 to indicate that you want to use anigraph instance discoverable withpkg-config:

IGRAPH_USE_PKG_CONFIG=1 pip install igraph

Alternatively, if you have already downloaded and extracted the source codeof igraph, you can runpip install on the source tree directly:

IGRAPH_USE_PKG_CONFIG=1 pip install.

(Note that you need theIGRAPH_USE_PKG_CONFIG=1 environment variablefor both invocations, otherwise the call topip install would stillbuild the vendored C core instead of linking to an existing installation).

This option is primarily intended for package maintainers in Linuxdistributions so they can ensure that the packaged Python interface links tothe packaged igraph library instead of bringing its own copy.

It is also useful on macOS if you want to link to the igraph library installedfrom Homebrew.

Due to the lack of support ofpkg-config on MSVC, it is currently notpossible to build against an external library on MSVC.

In case you are already using a MSYS2/MinGW and already havemingw-w64-igraph installed,simply type:

IGRAPH_USE_PKG_CONFIG=1 SETUPTOOLS_USE_DISTUTILS=stdlib pip install igraph

to build.

Warning: the Python interface is guaranteed to work only with the sameversion of the C core that is vendored inside thevendor/source/igraphfolder. While we try hard not to break API or ABI in the C core of igraphbetween minor versions in the 0.x branch and we will keep on doing so for majorversions once 1.0 is released, there are certain functions in the C API thatare marked asexperimental (see the documentation of the C core for details),and we reserve the right to break the APIs of those functions, even if they arealready exposed in a higher-level interface. This is because the easiest way totest these functions in real-life research scenarios is to expose them in oneof the higher level interfaces. Therefore, if you unbundle the vendored sourcecode of igraph and link to an external version instead, we can make noguarantees about stability unless you link to the exact same version as theone we have vendored in this source tree.

If you are curious about which version of the Python interface is compatiblewith which version of the C core, you can look up the corresponding tag inGithub and check which revision of the C core the repository points to inthevendor/source/igraph submodule.

If you want to install the development version, the easiest way to do so is toinstall it using

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

This automatically fetches the development version from the repository, buildsthe package and installs it. By default, this will install the Python interfacefrom themain branch, which is used as the basis for the development of thecurrent release series. Unstable and breaking changes are being made in thedevelop branch. You can install this similarly by doing

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

In addition togit, the installation of the development version requires someadditional dependencies, read further below for details.

For more information about installing directly fromgit usingpip seehttps://pip.pypa.io/en/stable/topics/vcs-support/#git.

Alternatively, you can clone this repository locally. This repository contains amatching version of the C core ofigraph as a git submodule. In order toinstall the development version from source, you need to instruct git to checkout the submodules first:

git submodule update --init

Compiling the development version additionally requiresflex andbison. Youcan install those on Ubuntu using

sudo apt install bison flex

On macOS you can install these from Homebrew or MacPorts. On Windows you caninstallwinflexbison3 from Chocolatey.

Then you can install the package directly withpip (see also the previous section):

pip install.

If you would like to create a source distribution or a Python wheel instead ofinstalling the module directly in your Python environment, use a standard buildfrontend likebuild. If youusepipx to isolate command-line Python toolsin their own separate virtualenvs, you can simply run:

pipx run build

Unit tests can be executed from within the repository directory withtox orwith the built-inunittest module:

python -m unittest

Note that unit tests have additional dependencies like NumPy, PIL ormatplotlib. The unit test suite will try to do its best to skip testsrequiring external dependencies, but if you want to make sure that all the unittests are executed, either usetox (which will take care of installing thetest dependencies in a virtualenv), or install the module with thetestextras:

pip install'.[test]'

Contributions toigraph are welcome!

If you want to add a feature, fix a bug, or suggest an improvement, open anissue on this repository and we'll try to answer. If you have a piece of codethat you would like to see included in the main tree, open a PR on this repo.

To start developingigraph, follow the steps above about installing the development version. Make sure that you do so by cloning the repository locally so that you are able to make changes.

For easier development, you can installigraph in "editable" (i.e.development) mode so your changes in the Python source code are picked upautomatically by Python:

pip install -e.

Changes that you make to the Python code do not need any extra action. However,if you adjust the source code of the C extension, you need to rebuild it by runningpip install -e . again. Compilation of the C core ofigraph iscached invendor/build andvendor/install so subsequent builds are muchfaster than the first one as the C core does not need to be recompiled.

We aim to keep up with the development cycle of Python and support all officialPython versions that have not reached their end of life yet. Currently thismeans that we support Python 3.9 to 3.13, inclusive. Please refer tothispage for the status of Pythonbranches and let us know if you encounter problems withigraph on anyof the non-EOL Python versions.

Continuous integration tests are regularly executed on all non-EOL Pythonbranches.

This version of igraph is compatible withPyPy andis regularly tested onPyPy withtox. However, thePyPy version falls behind the CPython version in terms of performance; forinstance, running all the tests takes ~5 seconds on my machine with CPython and~15 seconds with PyPy. This can probably be attributed to the need foremulating CPython reference counting, and does not seem to be alleviated by theJIT.

There are also some subtle differences between the CPython and PyPy versions:

• Docstrings defined in the C source code are not visible from PyPy.

• GraphBase is hashable and iterable in PyPy but not in CPython. SinceGraphBase is internal anyway, this is likely to stay this way.