Building and Installing the KaHyPar Python Module from Source

January 2026

← Back to other guides

This guide shows you how to build KaHyPar’s Python bindings from source and manually installing the resulting shared library into Python’s site-packages. It works on an Apple M4 Pro chip with Python 3.12.8.

1. Clone the KaHyPar repository

Clone the repository with required submodules.

git clone --depth=1 --recursive https://github.com/kahypar/kahypar.git

Move into the repository directory.

cd kahypar

2. Create and enter the build directory

KaHyPar uses an out-of-tree build layout.

mkdir -p build
cd build
cmake .. \
  -DPYTHON_EXECUTABLE=$(python3 -c "import sys; print(sys.executable)") \
  -DCMAKE_BUILD_TYPE=Release \
  -DKAHYPAR_PYTHON_INTERFACE=ON

3. Build the Python bindings

Enter the Python build directory and compile the module.

cd python
make

4. Locate the compiled shared library

After building, a shared object (.so) file should be present.

ls -lh *.so
Note: The filename may differ depending on your Python version (for example, it may include cpython-312 in the name). Use the exact .so filename you see here in the copy step below.

5. Find your Python site-packages directory

Determine where Python installs packages. Note: this uses fish shell syntax.

set SITEPKG (python -c "import site; print(site.getsitepackages()[0])")

6. Install the module manually

Copy the compiled shared library into site-packages using the exact versioned filename.

cp kahypar.cpython-313-darwin.so "$SITEPKG/kahypar.cpython-313-darwin.so"
Note: Use the exact filename rather than a wildcard or a renamed kahypar.so — Python resolves imports using the versioned name (cpython-313-darwin). Renaming it will cause import kahypar to fail on some platforms.

7. Copy the KaHyPar configuration files

The partitioner requires .ini config files at runtime. Copy them from the source tree.

mkdir -p "$SITEPKG/kahypar/bin"
cp kahypar.cpython-313-darwin.so "$SITEPKG/kahypar/"
echo "" > "$SITEPKG/kahypar/__init__.py"  # or copy the real one if it exists
cp ../../config/*.ini "$SITEPKG/kahypar/config/"

8. Return to your original directory

cd ../../../

9. Verify the installation

Check that Python can successfully import KaHyPar.

python -c "import kahypar; print('OK:', [x for x in dir(kahypar) if not x.startswith('_')])"

Expected output:

OK: ['ConnectivitySet', 'Context', 'Hypergraph', 'connectivityMinusOne', 'createHypergraphFromFile', 'cut', 'imbalance', 'partition', 'soed']
Common pitfalls: