Quick Start

Quick Start#

This guide walks you through building a Python package with C extensions for WebAssembly using pyodide-build. Make sure you’ve installed pyodide-build first.

Note

Pure Python packages do not need pyodide-build. If your package has no C, C++, or Rust extensions, a standard wheel built with python -m build already works with Pyodide.

Build from your source tree#

If you have a package with compiled extensions locally, build it the same way you would with python -m build:

pyodide build .

The output wheel is placed in ./dist/ by default:

dist/your_package-1.0.0-cp314-cp314-pyemscripten_2026_0_wasm32.whl

On the first run, pyodide-build automatically downloads and sets up the cross-build environment and Emscripten SDK. This may take a minute — subsequent builds are fast.

You can specify a different output directory with --outdir / -o:

pyodide build . -o wheelhouse/

Passing options to the build backend#

Use -C / --config-setting to pass options to your build backend, just like with python -m build:

# Meson project: pass the cross-compilation file
pyodide build . -C setup-args="--cross-file=your-emscripten-cross-file.txt"

# setuptools project: pass extra compile args
pyodide build . -C "--build-option=--some-flag"

Verify the wheel#

You can inspect the built wheel to confirm it has the correct platform tag:

unzip -l dist/your_package-*.whl | head -20

The wheel should contain .so files (compiled extensions) alongside your Python source, and the filename should include the pyemscripten_*_wasm32 platform tag.

Test the wheel#

Create a Pyodide virtual environment to test the wheel:

pyodide venv .venv-pyodide
source .venv-pyodide/bin/activate
pip install dist/your_package-*.whl
python -c "import your_package; print('it works!')"

See Testing with pyodide venv for a full walkthrough.

What’s next?#