libigl Python Bindings

This repository contains the source code for the python bindings for the C++ libigl library written using nanobind. Functions allow NumPy arrays as input and output for dense matrices and vectors and SciPy sparse matrices for sparse matrices.

Installation

python -m pip install libigl

Pyodide (WebAssembly)

Wheels for Pyodide 314.0 (Python 3.14, wasm32) are built and tested alongside the native wheels. In Pyodide, install the development release with:

import micropip
await micropip.install("libigl", pre=True)
import igl

These wheels include igl.embree, igl.copyleft.cgal, and type stubs for all modules. Geometry processing runs without worker threads. CGAL uses Boost exact arithmetic and its round-to-nearest interval implementation; Embree uses WebAssembly SIMD. Stubs are generated from the compiled modules inside Pyodide before the wheel is tested and published.

Documentation

⚠️ WARNING
The python-binding documentation is perennially out of date and will likely be removed/changed.

• A tutorial on how to use the bindings can be found here
• A function reference can be found here

Getting the current version of libigl within python code

Since version 2.5.4.dev0, the igl.__version__ attribute has been removed. To get the version of the libigl package you're using within your python code, you can use the following code:

import importlib.metadata
libigl_version = importlib.metadata.version('libigl')

The version of libigl is defined in the pyproject.toml file.

Compiling and modifying the bindings

According to the scikit-build-core documentation, the way to make an editable (incremental) build is to:

1. Preinstall the dependencies (at the top of pyproject.toml
2. Then use this very long command:

CMAKE_BUILD_PARALLEL_LEVEL=10  python -m pip install --no-build-isolation --config-settings=editable.rebuild=true -Cbuild-dir=build -ve.

The CMAKE_BUILD_PARALLEL_LEVEL=10 will invoke with 10 parallel build threads.

Adding a missing binding

Bindings are fairly mechanical to write. For example, suppose we didn't have a binding for the c++ function igl::moments. The first step would be to look at the corresponding .h header file in the C++ libigl library: moments.h.

Then we would create the src/moments.cpp file in this project which uses Eigen::MatrixXN for numeric types and Eigen::MatrixXI for integer types. Typically this requires a simple wrapper around the function matching its signature to these types and some boilerplate void bind_moments(... code which adds the function to the python module.

Simply adding this .cpp file will be enough to add the bindings on the next build.

If submitting a pull request with a new binding, please also add an execution test in tests/test_all.py to ensure the binding can at least be called as expected.

Packaging a wheel from an existing build

If you already have a compiled build directory, you can package it into a .whl without recompiling and install that wheel into other virtual environments on the same machine:

python -m pip wheel --no-build-isolation --no-deps -Cbuild-dir=build -w wheelhouse .
pip install wheelhouse/libigl-*.whl

The --no-deps flag skips bundling numpy/scipy (the target environment must have them already). No compiler or CMake is required in the target environment.

Testing cibuildwheel locally

To build and test the Pyodide wheel on Linux or macOS, use Python 3.14 and Node.js 24:

python -m pip install cibuildwheel==4.3.5
python -m cibuildwheel --platform pyodide --output-dir wheelhouse

Install whichever version of Python from the official website and then run:

/Library/Frameworks/Python.framework/Versions/3.11/bin/python3.11 -m venv venv-official-3.11
source venv-official-3.11/bin/activate
python -m pip install cibuildwheel
CIBW_BUILD="cp311-*" python -m cibuildwheel --output-dir wheelhouse --platform macos

Downloading all the artifacts

A successful .github/workflows/wheels.yml run will a lot of .whl files. To download these all at once, you can use the following command:

mkdir wheelhouse
cd wheelhouse
gh run download [runid]

Then these can be uploaded to pypi using:

for f in wheelhouse/*/*.whl wheelhouse/*/*.tar.gz; do
    python3 -m twine upload --repository pypi "$f" || echo "Skipping failed upload: $f"
done

Acknowledgements

The original python bindings were generated and maintained by @teseoch, @KarlLeell, @fwilliams, @skoch9, and @danielepanozzo

The modern python bindings (since 2.5.4.dev0) can largely be blamed on @alecjacobson.