Installation

This guide covers how to install multigedi on different platforms.

Prerequisites

multigedi requires:

  • Python >= 3.10

  • C++ compiler with C++17 support

  • Eigen3 >= 3.3 (linear algebra library)

  • CMake >= 3.15 for CPU builds; >= 3.18 for GPU builds

conda

Using conda to manage dependencies (recommended for complex environments):

# Create environment with system dependencies
conda create -n multigedi python=3.11 cmake eigen compilers -c conda-forge
conda activate multigedi

# Install the downloaded release wheel
python -m pip install /path/to/multigedi-1.7.1-<python>-<abi>-<platform>.whl

From source

For development or to get the latest features:

# Clone the latest stable tag
git clone --branch v1.7.1 --depth 1 https://github.com/csglab/multigedi.git
cd multigedi

# Build and install locally
python -m pip install .

Contributors who need current main should clone without --branch and use python -m pip install -e ".[dev,test]".

Building from source requirements

macOS

# Install Xcode command line tools (provides C++ compiler)
xcode-select --install

# Install Eigen via Homebrew
brew install eigen cmake

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y build-essential cmake libeigen3-dev

Fedora/RHEL

sudo dnf install gcc-c++ cmake eigen3-devel

Windows

Windows wheels are not currently part of the release matrix. We recommend using Windows Subsystem for Linux (WSL2) with Ubuntu. Native Windows source builds are not verified.

GPU backend

The GPU backend requires CMake >= 3.18, an NVIDIA CUDA toolchain, and OpenMP. It is built together with its in-memory pybind11 module:

python -m pip install . --config-settings=cmake.define.MULTIGEDI_BUILD_GPU=ON -v

Use a CUDA 12 toolchain for the supported release configuration. A GPU-enabled build is required on the machine that compiles the package; running GPU tests also requires a visible CUDA device.

Verify installation

After installation, verify multigedi is working:

import multigedi as gd
print(gd.__version__)

# Check that the C++ backend loads
from multigedi import _multigedi_cpp
print("C++ backend loaded successfully")

Optional dependencies

scanpy integration

For full scverse integration, install scanpy:

python -m pip install scanpy

UMAP

UMAP is intentionally optional:

python -m pip install "umap-learn>=0.5"

Troubleshooting

ImportError: Cannot load C++ extension

This usually means the C++ extension failed to build. Check that:

  1. You have a C++ compiler installed

  2. Eigen3 is installed and findable by CMake

  3. CMake >= 3.15 is available

Try reinstalling with verbose output:

python -m pip install /path/to/downloaded/multigedi-source-checkout -v

Permission errors

Never use sudo pip. Instead:

# Use --user flag
python -m pip install --user /path/to/downloaded/multigedi-wheel.whl

# Or better, use a virtual environment
python -m venv multigedi-env
source multigedi-env/bin/activate  # Linux/macOS
python -m pip install /path/to/downloaded/multigedi-wheel.whl

Eigen3 not found

If CMake cannot find Eigen3, you can specify the path:

CMAKE_PREFIX_PATH=/path/to/eigen3 python -m pip install /path/to/multigedi-source-checkout

Or on conda:

conda install eigen -c conda-forge

OpenMP on macOS

Published macOS wheels are intentionally single-threaded because Apple Clang does not provide OpenMP by default. Source builds use OpenMP when CMake finds a compatible implementation; otherwise they fall back cleanly to one thread.

Development installation

For contributing to multigedi:

git clone https://github.com/csglab/multigedi.git
cd multigedi

# Install with all development dependencies
python -m pip install -e ".[dev,test,docs]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest