Building a Pyodide Wheel for Cantera#

Cantera can be built as a Pyodide-compatible wheel so the Python module can run in browser-based environments (for example, JupyterLite).

This page documents the local and CI workflow used in this repository for generating and smoke-testing that wheel.

Overview#

The Pyodide build follows the same two-stage packaging model as the standard Python wheel flow:

  1. Build an sdist from the Cantera source tree using SCons.

  2. Build the wheel from that sdist using the Pyodide toolchain.

The SCons entry point for this is:

scons pyodide-wheel

Output wheels are written to:

build/pyodide_dist/

Requirements#

The Pyodide build uses the dedicated pyodide Pixi environment in pixi.toml. At minimum, this environment needs:

  • Python 3.13

  • SCons

  • pyodide-build

  • build

  • scikit-build-core

  • CMake and Ninja

  • Boost headers (boost-cpp)

  • Cantera’s Python build dependencies (cython, numpy, ruamel.yaml, pip)

Note

When using pyodide venv, the generated interpreter requires node to be available on PATH. This can be achieved by running Pyodide venv commands through Pixi as pixi run -e pyodide ... so the right runtime is present.

Local Build#

From the repository root:

pixi run -e pyodide scons pyodide-wheel

This creates a wheel named something like:

build/pyodide_dist/cantera-<version>-cp313-cp313-pyodide_<abi>_wasm32.whl

Local Testing#

To test the Pyodide wheel locally, you can set up a Pyodide venv and install the wheel and run one of the Cantera examples:

pixi run -e pyodide pyodide venv .pyodide-venv
WHEEL=$(ls build/pyodide_dist/cantera-*.whl)
pixi run -e pyodide .pyodide-venv/bin/pip install "$WHEEL"
pixi run -e pyodide .pyodide-venv/bin/python samples/python/thermo/rankine.py

To run other examples, you may need to install additional packages like Matplotlib and Pandas in this venv.

CI Job and Artifacts#

The pyodide-wheel CI job in .github/workflows/main.yml does the following:

  1. Builds the Pyodide wheel via scons pyodide-wheel.

  2. Creates a Pyodide virtual environment.

  3. Installs the built wheel.

  4. Uploads the wheel as a GitHub artifact (cantera-wheel-pyodide).

  5. Runs the Python unit test suite using Pyodide.

Common Pitfalls#

  • Wrong import target during testing: If pytest imports build/python/cantera instead of the wheel, clear path overrides such as PYTHONPATH and verify import cantera; print(cantera.__file__).

  • No node executable found on the path: Run .pyodide-venv/bin/python through pixi run -e pyodide ... so the Node runtime from that environment is available.

  • JupyterLite --piplite-wheels path confusion: --piplite-wheels paths are resolved relative to --lite-dir, not the current working directory.

On this page
Show Source