leidenalg: the Leiden community detection algorithm in Python

What the package is and where it sits

leidenalg implements the Leiden algorithm in C++ and exposes it to Python, and it relies on python-igraph to function. The README describes it as made for flexibility, and says that besides the relative flexibility of the implementation it also scales well, and can be run on graphs of millions of nodes as long as they can fit in memory.

The core function is find_partition, which finds the optimal partition using the Leiden algorithm. The algorithm itself is an extension of the Louvain algorithm, and the reference given is Traag, Waltman and Van Eck, From Louvain to guaranteeing well-connected communities, in Scientific Reports in 2018.

The relationship with igraph is the important part of understanding the package. The README says igraph nowadays also includes an implementation of the Leiden algorithm internally, and that this implementation is less flexible: it only works on undirected graphs, and only CPM and modularity are supported. It is likely to be substantially faster though.

So there are two implementations of the same algorithm available to a Python user, and the trade is explicit in the README. If you want the fastest partition of an undirected graph by modularity, use the one inside igraph. If you need anything else, this is the package.

The repository is a Python wrapper with C++ sources, a src/ directory, an include/ directory, a scripts/ directory with the build helpers, a doc/ directory, a tests/ directory, a setup.py, a pyproject.toml and a CHANGELOG file. The licence field on the repository says GPL-3.0 and the package metadata says GPL-3.0-or-later.

The objectives the package supports

The list of quality functions is the substance of the package, and the README names five.

First, modularity, the objective from Newman and Girvan. Second, the Reichardt and Bornholdt model using either the configuration null model or the Erdös-Rényi null model, which is the statistical mechanics formulation of community detection. Third, the Constant Potts model, or CPM, from Traag, Van Dooren and Nesterov. Fourth, Significance. Fifth, Surprise.

The Constant Potts model deserves a note, because it is the reason the Leiden algorithm exists. The CPM paper is titled Narrow scope for resolution-limit-free community detection, and the resolution limit is the well known problem where modularity cannot detect communities smaller than a scale that depends on the size of the network, so a large graph with small genuine communities gets merged into one. CPM is the standard workaround, and the paper's title is an argument that its scope is narrower than generally assumed.

On top of the single-graph objectives there is multiplex partition optimisation, which allows community detection on things like negative links, where an edge means antagonism, or on multiple time slices, where the same entities appear in several snapshots and you want communities that hold across time. That is a materially different problem from clustering one graph, and having it in the same package with the same objective machinery is the point.

There is also the possibility of only partially optimising a partition, so that some community assignments remain fixed. That is a practical feature rather than an exotic one, since it lets you extend a partition you already trust rather than starting from scratch.

And there is some support for community detection on bipartite graphs, which needs its own objective handling because a bipartite graph has no triangles to work with.

Installing the wheel and building from source

The short answer is pip install leidenalg. All major platforms are supported on Python 3.9 and later, and earlier versions of Python are no longer supported. Alternatively you can install from Anaconda on the conda-forge channel, and the README carries a badge for that channel.

The source route is described in detail, and the ordering matters. The Python interface depends on the C++ package libleidenalg, which in turn depends on igraph, so you need to build these packages yourself before you can build the Python interface.

The build tools on Ubuntu are installed with a single package line.

sudo apt-get install build-essential autoconf automake flex bison

The README warns to make sure not only gcc is installed but also g++, since the leidenalg package is programmed in C++.

Then there are three steps. First, compile and install the C core of igraph, version 1.0.0 or later, using the build_igraph.sh file on Unix-like systems or build_igraph.bat on Windows, both in the scripts/ directory. Second, compile and install the C core of libleidenalg, version 0.12 or later, using build_libleidenalg.sh or build_libleidenalg.bat in the same directory. Third, build the Python interface with python setup.py build and python setup.py install, or use pip install.

The version floors are consistent across the README and the metadata, since pyproject.toml requires igraph at 1.0.0 or later and below 2.0, and requires Python 3.7 or later even though the README says 3.9 and later for the wheels.

You can check the install worked by running the tests with python -m unittest. The troubleshooting advice is blunt about starting over: remove the igraph and leidenalg packages completely and do a clean reinstall, and if you built the C libraries yourself, remove those too and rebuild.

The setup.py also shows an interesting packaging detail. On CPython 3.8 and later the wheel is built against the limited API with the Py_LIMITED_API macro set to 0x03090000, and the wheel tag is rewritten to cp38 abi3, which means one binary wheel works across Python 3.8 and later.

Using it from Python

The README gives the essentials, and they are short enough to be the whole first hour of use.

>>> import leidenalg
>>> import igraph as ig

>>> G = ig.Graph.Erdos_Renyi(100, 0.1);

>>> part = leidenalg.find_partition(G, leidenalg.ModularityVertexPartition);

The pattern is that the graph comes from igraph, since igraph is the graph library, and leidenalg is the partitioner. The objective is passed as a class rather than as a flag, leidenalg.ModularityVertexPartition, and the partition object that comes back carries the community assignment and the objective value.

The README points to the documentation at leidenalg.readthedocs.io for the details of function calls and parameters, and specifically to the section on Implementation for how to add new methods.

That last point matters if you want to extend it, because the package is deliberately structured so that the quality functions are pluggable, and the C++ package libleidenalg is where the actual algorithms live, with the Python side being a thin interface over it. If you are adding a new objective, the C++ package is where the work happens.

The package also publishes a DOI through Zenodo, which is the citation handle for a research artifact rather than a repository release, and the readthedocs badge tracks the documentation build.

Where leidenalg is the wrong choice

The first limitation is the one the README states plainly. This implementation is made for flexibility, but igraph nowadays also includes an implementation of the Leiden algorithm internally, and that implementation is less flexible, working only on undirected graphs and supporting only CPM and modularity. It is likely to be substantially faster though.

So for a plain undirected graph partitioned by modularity, there is a faster path, and choosing the flexible one is a deliberate trade of speed for capability. If your analysis is that simple, you are paying for options you do not use.

The second limitation is the modularity resolution limit, which is a property of the objective rather than of the implementation. Modularity has a known scale below which it merges genuine small communities, and no amount of algorithmic care fixes it. The Constant Potts model is the tool for that, and choosing it means choosing a resolution parameter, which is a different set of judgement calls.

The third is the build complexity for a source install. Three packages have to be built in order, igraph then libleidenalg then the Python interface, and the README is explicit that you have to build the C libraries yourself before the Python one. On Windows the README recommends the binary wheels instead, which is a reasonable admission that the source path there is more complicated.

The fourth is the licence. GPL-3.0-or-later is fine for academic work and for most research code, and it is worth noting that a GPL library linked into a closed-source product is a distribution question with a legal answer, not a technical one.

The fifth is the maturity label. The pyproject classifies the project as Development Status 4 - Beta, and the release history is slow, with 0.12.0 from 2026-05-24, 0.11.0 from 2025-10-31 and 0.10.0 from 2023-07-14. The package is stable in use, but the release train is not fast, and a project that needs a new objective will be waiting on the C++ package.

How it compares with igraph's built-in Leiden and with the Louvain implementations

The comparison with igraph's internal implementation is the direct one and the README settles it in two sentences. The difference in approach is the objective coverage, since igraph's version does modularity and CPM on undirected graphs, and this one does five objectives, plus multiplex optimisation, plus partial optimisation with fixed assignments, plus bipartite support. The cost is speed.

So the practical rule is: if you want modularity or CPM on an undirected graph and nothing more, call igraph's version; if your problem needs one of the other objectives, or needs to hold some assignments fixed, or involves negative links or multiple time slices, this is the only one of the two that can do it.

The comparison with the Louvain implementations, in igraph, NetworkX or elsewhere, is about the algorithm rather than the packaging. Louvain is the predecessor, and the Leiden paper's contribution is a guarantee: Louvain can return a partition with internally disconnected communities, which means the algorithm's own output can be wrong in a way that is invisible without checking. Leiden guarantees well-connected communities. If your analysis depends on every community being internally connected, that guarantee is the reason to use Leiden at all rather than Louvain, and it is a correctness argument rather than a quality-of-results argument.

The third comparison is with the R ports the README lists, leidenbase, leiden and leidenAlg. The README says there are no plans for an R interface and that the various efforts to port the package to R typically do not offer all available functionality or have some other limitations, but may still be very useful. So the R situation is a set of partial ports rather than a maintained official binding, and that is the practical difference for an R shop.

The fourth comparison is with dedicated standalone tools such as the standalone Leiden implementations or the community detection tools inside Gephi or Cytoscape. The difference is that those are applications for a human looking at a picture of a network, and this is a library for a script that has to produce a partition as part of a pipeline.

Licence, maintenance and what to check before using it

The licence field on the repository says GPL-3.0, and the package metadata records it as GPL-3.0-or-later, with the trove classifiers naming the Mozilla Public License 2.0 elsewhere in the ecosystem, but this project's own metadata is explicit about the GPL. The LICENSE file sits at the root of the repository.

The project is not archived and the last push was on 2026-10-19, so it is being worked on, and the release history shows 0.12.0 from 2026-05-24, 0.11.0 from 2025-10-31 and 0.10.0 from 2023-07-14.

The package is built with setuptools and setuptools_scm, so the version is derived from the repository tags and written to src/leidenalg/version.py at build time, which is why the release numbering is a single decimal line rather than the usual calendar versioning.

The Python interface is a single C extension module, leidenalg._c_leiden, compiled from the C++ sources under src/leidenalg and linked against libleidenalg and igraph, with the include and library directories pointing at a build-deps/install prefix, which is where the earlier build steps put the C libraries.

Four things to check before you rely on it.

Which objective your question actually needs, because modularity has a resolution limit and the Constant Potts model has a resolution parameter, and picking the wrong one produces a partition that looks reasonable and answers a different question.

Whether you need the igraph version instead, since the README says it is likely to be substantially faster for the simple case.

Whether your environment can install igraph at 1.0.0 or later and below 2.0, since that is the declared dependency range.

And whether the licence suits your context, since GPL-3.0-or-later on a library you link into a product is a distribution question to settle before you ship.

Editorial conclusion

leidenalg suits a researcher who needs an objective other than plain modularity, who needs to fix some community assignments, or who needs to work on multiplex or bipartite graphs, since igraph's built-in implementation covers less of that ground. It is the wrong tool if you want the fastest possible result on a plain undirected modularity partition, because the README says igraph's internal implementation is likely to be substantially faster. Before choosing it, check the objective your question needs against the list in the README, since the resolution limit problem that motivates the Constant Potts model is the reason the package exists at all.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. vtraag/leidenalg on GitHub