Infomap

Infomap is a network clustering algorithm based on the Map equation. This repository contains the native CLI, the Python package, the R package, the JavaScript browser worker and Node.js package, the Docker images, the tutorial notebooks, and the source for the published Python documentation.

Start with mapequation.org/infomap/ for the user guide, the Infomap Python API for Python examples and tutorial notebooks, and CHANGELOG.md for release notes.

For contributing, security reporting, and maintainer workflows, see CONTRIBUTING.md, SECURITY.md, BUILD.md, ARCHITECTURE.md, and AGENTS.md.

Install

Python package

Install from PyPI:

pip install infomap

Install optional integrations for common Python graph and analysis workflows:

pip install "infomap[networkx]"
pip install "infomap[igraph]"
pip install "infomap[pandas]"

Upgrades use the usual pip flow:

pip install --upgrade infomap

The package also installs the infomap CLI entry point. The Python API reference lives at Infomap Python API.

Quick start with Python:

import networkx as nx
import infomap

graph = nx.karate_club_graph()
result = infomap.run(graph, seed=123, num_trials=20)

print(result.num_top_modules, result.codelength)
print(result.modules())  # {node_id: module_id}

infomap.run accepts a NetworkX or igraph graph, a SciPy sparse matrix, a (2, E) edge index, a network file path, or an iterable of links. It returns an immutable Result. If you only need the communities in the graph's own node labels, use infomap.find_communities(graph, seed=123, num_trials=20), which returns a NetworkX-style list of sets of node labels. Its igraph counterpart infomap.find_igraph_communities returns an igraph.VertexClustering.

For incremental construction -- adding nodes and links one at a time -- build a Network and run it, reading results off the returned Result:

from infomap import Network, run

net = Network()
net.add_link(0, 1)
net.add_link(1, 2)
result = run(net, two_level=True, num_trials=20, seed=123)

print(result.num_top_modules, result.codelength)
print(result.to_dataframe(columns=["node_id", "module_id", "flow"], index="node_id"))

The stateful Infomap class works the same way (im = Infomap(...); im.add_link(...); result = im.run()). Use it to keep one configured engine and run it repeatedly, or to maintain code written against the original API.

For Jupyter, start with the quickstart notebook. It shows the Infomap result summary, dataframe inspection, a copyable static network partition helper, and export paths for further analysis.

R package

Pre-built binaries are published on r-universe; this is the recommended path:

install.packages(
  "infomap",
  repos = c("https://mapequation.r-universe.dev", "https://cloud.r-project.org")
)

Quick start with R:

library(infomap)

im <- Infomap(silent = TRUE, two_level = TRUE, num_trials = 20)
im$add_link(0, 1)
im$add_link(1, 2)
im$run()

print(im$num_top_modules)
print(im$codelength)

See ?Infomap for the user-facing constructor plus the InfomapClass method and active-binding reference. The R-specific source README lives at interfaces/R/infomap/README.md.

Homebrew CLI

If you want the native CLI without the Python package, install the tap and formula with:

brew tap mapequation/infomap
brew install infomap

Or install directly in one command:

brew install mapequation/infomap/infomap

Upgrade the CLI with the normal Homebrew flow:

brew upgrade infomap

The Homebrew formula installs Bash and Zsh completion files into Homebrew's standard completion directories.

JavaScript package

The package is published on NPM and provides a browser web worker, a Node.js module, and an infomap command line tool:

npm install @mapequation/infomap

Quick start in Node.js with the @mapequation/infomap/node entry point:

import { run } from "@mapequation/infomap/node";

const network = "0 1\n0 2\n0 3\n1 2\n3 4\n3 5\n4 5";
const result = await run(network, { args: ["-o", "tree,json", "-2"] });

console.log(result.json.codelength);
console.log(result.tree);

Installing the package also provides an infomap command that behaves like the native binary:

npx @mapequation/infomap network.net . --tree

The NPM package page documents browser worker and React usage.

Docker

Multi-arch images are published to GHCR for linux/amd64 and linux/arm64:

• ghcr.io/mapequation/infomap:latest
• ghcr.io/mapequation/infomap:X.Y.Z
• ghcr.io/mapequation/infomap:notebook
• ghcr.io/mapequation/infomap:notebook-X.Y.Z

Run the CLI image with:

docker run -it --rm \
    -v "$(pwd)":/data \
    ghcr.io/mapequation/infomap:latest \
    [infomap arguments]

Start the notebook image with:

docker run --rm \
    -p 8888:8888 \
    ghcr.io/mapequation/infomap:notebook \
    start.sh jupyter lab

The notebook image includes the survey companion notebooks from examples/notebooks and opens in that workspace by default. To keep local copies or outputs, mount a host directory as a separate workspace path:

docker run --rm \
    -v "$(pwd)":/home/jovyan/work/local \
    -p 8888:8888 \
    ghcr.io/mapequation/infomap:notebook \
    start.sh jupyter lab

CI also smoke-tests the Dockerfiles in this repository, and you can build them locally:

docker build -f docker/infomap.Dockerfile -t infomap:local .
docker build -f docker/notebook.Dockerfile -t infomap:notebook-local .

Or use the local Compose file:

docker compose run --rm infomap

Build from source

Building locally requires a working gcc or clang toolchain.

git clone git@github.com:mapequation/infomap.git
cd infomap
make build-native

On macOS, the default OpenMP-enabled build can require Homebrew libomp. If OpenMP is unavailable, use:

make build-native OPENMP=0

This creates the Infomap binary in the repository root. Show the available CLI options with:

./Infomap --help

Install shell completion scripts manually with:

mkdir -p ~/.zfunc
./Infomap --completion zsh > ~/.zfunc/_Infomap

mkdir -p ~/.local/share/bash-completion/completions
./Infomap --completion bash > ~/.local/share/bash-completion/completions/infomap

For Zsh, make sure fpath contains ~/.zfunc and ~/.zshrc loads compinit. For Bash, make sure ~/.bashrc sources bash-completion.

See BUILD.md for platform-specific maintainer build details.

For maintainer tasks, use:

• BUILD.md for local build and verification commands
• RELEASING.md for the release flow
• ARCHITECTURE.md for ownership and source-of-truth rules
• AGENTS.md for repo-local maintenance guidance
• CONTRIBUTING.md for pull request and contributor guidance
• SECURITY.md for vulnerability reporting

Agent skill

This repository includes an Infomap agent skill in skills/infomap/ for reproducible CLI, Python, R, and notebook research workflows.

Feedback

Usage questions and setup help belong in GitHub Discussions. Bug reports and feature requests belong in GitHub issues.

Authors

Daniel Edler, Anton Holmgren, Martin Rosvall

For contact information, see mapequation.org/about.html.

Terms of use

Infomap is released under a dual license.

The code is available under the GNU General Public License version 3 or any later version; see LICENSE_GPLv3.txt. For a non-copyleft license, contact us.