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 web worker, the Docker images, and the source for the published Python documentation.

Start with mapequation.org/infomap/ for the user guide 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

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:

from infomap import Infomap, InfomapOptions

options = InfomapOptions(two_level=True, silent=True, num_trials=20)
im = Infomap.from_options(options)
im.add_link(0, 1)
im.add_link(1, 2)
im.run()

print(im.num_top_modules, im.codelength)

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

JavaScript package

The browser worker package is published on NPM:

npm install @mapequation/infomap

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 \
    -v "$(pwd)":/home/jovyan/work \
    -p 8888:8888 \
    ghcr.io/mapequation/infomap:notebook \
    start.sh jupyter lab

The Dockerfiles in this repository are also smoke-tested in CI and can be built 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 may 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

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

Maintainers should 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

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 licence.

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, please contact us.