Infomap is a network clustering algorithm based on the Map equation. This repository contains the native CLI, the Python 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.

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)

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 browser worker package is published on NPM:

npm install @mapequation/infomap

Supported images are published on Docker Hub:

• mapequation/infomap
• mapequation/infomap:notebook

Run the CLI image with:

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

Or use the local Compose file:

docker compose run --rm infomap

Start the notebook image with:

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

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

Questions, bug reports, and feature requests belong in GitHub issues.

Daniel Edler, Anton Holmgren, Martin Rosvall

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

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.