|ci|

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

.. |ci| image:: https://github.com/mapequation/infomap/actions/workflows/ci.yml/badge.svg :target: https://github.com/mapequation/infomap/actions/workflows/ci.yml :alt: CI

.. _Map equation: https://www.mapequation.org/publications.html#Rosvall-Axelsson-Bergstrom-2009-Map-equation .. _mapequation.org/infomap/: https://www.mapequation.org/infomap/ .. _CHANGELOG.md: https://github.com/mapequation/infomap/blob/master/CHANGELOG.md .. _CONTRIBUTING.md: https://github.com/mapequation/infomap/blob/master/CONTRIBUTING.md .. _SECURITY.md: https://github.com/mapequation/infomap/blob/master/SECURITY.md .. _BUILD.md: https://github.com/mapequation/infomap/blob/master/BUILD.md .. _ARCHITECTURE.md: https://github.com/mapequation/infomap/blob/master/ARCHITECTURE.md .. _AGENTS.md: https://github.com/mapequation/infomap/blob/master/AGENTS.md

Install

Python package ^^^^^^^^^^^^^^

Install from PyPI_:

.. code-block:: bash

pip install infomap

Install optional integrations for common Python graph and analysis workflows:

.. code-block:: bash

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

Upgrades use the usual pip flow:

.. code-block:: bash

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:

.. code-block:: python

import networkx as nx
import infomap

graph = nx.karate_club_graph()
communities = infomap.find_communities(
    graph,
    seed=123,
    num_trials=20,
)

print(communities)

For direct control over Infomap-specific options and result access:

.. code-block:: python

from infomap import Infomap, InfomapOptions

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

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

.. _PyPI: https://pypi.org/project/infomap/ .. _Infomap Python API: https://mapequation.github.io/infomap/

R package ^^^^^^^^^

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

.. code-block:: r

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

Quick start with R:

.. code-block:: 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_.

.. _r-universe: https://mapequation.r-universe.dev .. _interfaces/R/infomap/README.md: https://github.com/mapequation/infomap/blob/master/interfaces/R/infomap/README.md

Homebrew CLI ^^^^^^^^^^^^

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

.. code-block:: bash

brew tap mapequation/infomap
brew install infomap

Or install directly in one command:

.. code-block:: bash

brew install mapequation/infomap/infomap

Upgrade the CLI with the normal Homebrew flow:

.. code-block:: bash

brew upgrade infomap

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

JavaScript package ^^^^^^^^^^^^^^^^^^

The browser worker package is published on NPM_:

.. code-block:: bash

npm install @mapequation/infomap

.. _NPM: https://www.npmjs.com/package/@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:

.. code-block:: bash

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

Start the notebook image with:

.. code-block:: bash

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:

.. code-block:: bash

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:

.. code-block:: bash

docker compose run --rm infomap

.. _GHCR: https://github.com/mapequation/infomap/pkgs/container/infomap

Build from source

Building locally requires a working gcc or clang toolchain.

.. code-block:: bash

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:

.. code-block:: bash

make build-native OPENMP=0

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

.. code-block:: bash

./Infomap --help

Install shell completion scripts manually with:

.. code-block:: bash

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 ~/.zfunc is in fpath and compinit is loaded from ~/.zshrc. For Bash, make sure bash-completion is sourced from ~/.bashrc.

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.

.. _GitHub Discussions: https://github.com/mapequation/infomap/discussions .. _GitHub issues: https://github.com/mapequation/infomap/issues

Authors

Daniel Edler, Anton Holmgren, Martin Rosvall

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

.. _mapequation.org/about.html: https://www.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.

.. _LICENSE_GPLv3.txt: https://github.com/mapequation/infomap/blob/master/LICENSE_GPLv3.txt