CI Docs Docker smoke Nightly quality

Infomap

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.

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)

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

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

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.