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.