pyodide-build

pyodide-build#

Build Python packages for WebAssembly.

pyodide-build is the build toolchain for compiling Python packages to WebAssembly via Emscripten. It is the reference implementation of the build toolchain for the Emscripten/WebAssembly Python platform.

This tool is designed to be used with Pyodide, but it can also be used with other Emscripten-based Python runtimes that support the same platform tags that follows PEP 783.

If you’re familiar with python -m build, pyodide-build works the same way — just replace it with pyodide build:

pip install pyodide-build
pyodide build .

This produces a .whl file tagged for the Emscripten platform (e.g., your_package-1.0-cp314-cp314-pyemscripten_2026_0_wasm32.whl) that can be published to PyPI and installed in Pyodide.

Who is this for?#

Note

Pure Python packages do not need pyodide-build. A standard wheel built with python -m build, hatch, flit, or any PEP 517 build frontend is already compatible with Pyodide. pyodide-build is for packages that contain compiled extensions.

pyodide-build is for Python package maintainers who want their package to work in WebAssembly environments — the browser, Node.js, or any Emscripten-based Python runtime. Typical users include:

  • Package authors adding Pyodide/WebAssembly to their platform support matrix

  • Library maintainers whose users need the package in JupyterLite, Pyodide, or other browser-based Python environments

How it works#

pyodide-build wraps pypa/build with a cross-compilation layer. When you run pyodide build, it:

  1. Sets up a cross-build environment with Emscripten-compiled CPython headers

  2. Intercepts compiler calls (gcc, g++, ld, etc.) and redirects them to Emscripten (emcc, em++)

  3. Translates compiler flags for WebAssembly compatibility

  4. Produces a standard wheel with the appropriate platform tag

Your existing setup.py, pyproject.toml, CMakeLists.txt, or meson.build works as-is — pyodide-build handles the cross-compilation transparently.

Where to start#

Quick Start

Build your first WebAssembly wheel in 5 minutes.

getting-started/quickstart.html
CI with cibuildwheel

Add Pyodide to your existing cibuildwheel CI pipeline.

how-to/cibuildwheel.html
Testing with pyodide venv

Verify your wheel works in a Pyodide environment.

getting-started/testing.html

Communication#