Pyodide Local Build Environment

Goal¶

The folder ci_scripts/pyodide_local_build/ contains tools for building imgui-bundle as a Pyodide package locally (out-of-tree).

Recommended usage: Use the justfile targets from the repository root for a streamlined workflow.

> just pyodide_
pyodide_build               -- Args: # Build pyodide wheel (excludes demos to reduce size)
pyodide_clean               -- Args: # Clean pyodide build artifacts
pyodide_deep_clean          -- Args: # Pyodide deep clean (removes also the local build setup)
pyodide_demo_runner         -- Args: # Serve the pyodide demo runner
pyodide_serve_projects      -- Args: # Serve pyodide_projects/projects (test pages, playground, ...)
pyodide_setup_local_build   -- Args: # Install the tools to build pyodide wheels locally (pyodide-build, emsdk, etc.)
pyodide_setup_recipe_clone  -- Args: # Clone pyodide-recipes repo and add fork remote

What’s included:

• Python virtual environment with pyodide-build installed

• Emscripten SDK (emsdk) with the correct version for Pyodide

• Setup and build scripts

• Browser testing infrastructure

Directory Structure¶

imgui_bundle/
    ci_scripts/pyodide_local_build/
        ├── Readme.md                      # This file
        ├── config_versions_pyodide.sh     # Version configuration (edit this to change versions)
        ├── setup_pyodide_local_build.sh   # Automated setup script
        ├── .gitignore                     # Ignores venv_pyo/ and emsdk/
        ├── venv_pyo/                      # Python virtual environment (created during setup)
        └── emsdk/                         # Emscripten SDK (created during setup)
    pyodide_projects/
        ├── pyodide_test_bundle/           # Browser testing tools and HTML test pages

Both venv_pyo/ and emsdk/ are gitignored and must be set up locally.

Configuration¶

Before setup, you can customize versions by editing config_versions_pyodide.sh:

# Pyodide version to use (determines ABI compatibility)
PYODIDE_VERSION="314.0.0"

# Python version (major.minor, e.g., "3.14")
PYTHON_VERSION="3.14"

This central configuration file is used by all build scripts in this directory.

Setup Instructions¶

Quick Setup (Recommended)¶

From the repository root, use the justfile target:

just pyodide_setup_local_build

This will automatically set up the complete build environment.

Manual Setup¶

Alternatively, run the setup script directly:

cd ci_scripts/pyodide_local_build
./setup_pyodide_local_build.sh

The setup script will:

1. Load version configuration from config_versions_pyodide.sh

2. Create the Python virtual environment (venv_pyo/)

3. Install pyodide-build

4. Install the Pyodide cross-compilation toolchain (xbuildenv)

5. Clone and configure Emscripten SDK with the correct version

6. Verify the installation

Reference: https://pyodide.org/en/stable/development/building-packages.html

Building imgui-bundle¶

Quick Build (Recommended)¶

From the repository root, use the justfile target:

just pyodide_build

This automatically:

1. Activates the virtual environment

2. Sources the Emscripten environment

3. Builds the wheel with pyodide build

4. Copies the wheel to the local_wheels/ folders under pyodide_projects/ for testing

Manual Build¶

If you prefer to run steps manually:

# 1. Activate environments
source ci_scripts/pyodide_local_build/venv_pyo/bin/activate
source ci_scripts/pyodide_local_build/emsdk/emsdk_env.sh

# 2. Build from repository root
cd ../..  # Go to imgui_bundle root
pyodide build

Output¶

After building, you’ll find the wheel in the dist/ directory:

dist/imgui_bundle-X.Y.Z-cp314-cp314-pyemscripten_2026_0_wasm32.whl

Browser Testing¶

Test your locally built wheel in a browser with Pyodide:

just pyodide_serve_projects

This starts a CORS-enabled web server at http://localhost:6456/ ; open pyodide_test_bundle/test_cdn_pyodide_local_wheel.html (CDN Pyodide + local wheel). The playground and min_pyodide_app are served there too.

Cleanup¶

Remove build artifacts:

just pyodide_clean

Deep clean (removes build artifacts, downloaded Pyodide distribution, and build environment):

just pyodide_deep_clean

References¶

• Pyodide Build Docs: https://pyodide.org/en/stable/development/building-packages.html

• Pyodide ABI: https://pyodide.org/en/stable/development/abi.html

• Emscripten SDK: https://emscripten.org/docs/getting_started/downloads.html

• scikit-build-core issue #920: scikit-build/scikit-build-core#920

Release a new version for Pyodide¶

• Before the release: build & test the new version locally with pyodide (see above)

• At the release, the pyodide.yml CI workflow builds the wheel and uploads it to PyPI (PEP 783 pyemscripten wheels are accepted there since Pyodide 314 / pyodide-build 0.35) and to the GitHub release: nothing to do by hand. Only if that upload failed: uv tool run twine upload dist/imgui_bundle-*pyemscripten*.whl

• micropip then resolves it directly: micropip.install("imgui-bundle")

Note: the former channel (a recipe in https://github.com/pyodide/pyodide-recipes, shipped with the Pyodide distribution) is deprecated for imgui-bundle: the recipe there is disabled, so micropip falls through to PyPI.