PyPI package distribution - Dear ImGui Bundle

Release process¶

Update the version number in pyproject.toml and CMakeLists.txt (they must match). Version scheme: ImGui patch × 100 + bundle release (e.g. 1.92.601 = ImGui 1.92.6, bundle release 1). Also update Pyodide wheel filenames hardcoded in demos / docs — see cloudflare_deploy.md → wheel filename references.
Check the web builds (Emscripten and Pyodide): see Web checks before a release. After an update of Dear ImGui, also check a third party renderer: see Third party renderers check. Retake the API pages’ pictures of the demo sections whose code changed: just imex_ems_build, then just api_pictures --stale, and review them (--sheet, see the docstring of ci_scripts/api_pictures.py).
Create a GitHub release with a new tag (e.g. v1.92.601). The wheels.yml CI workflow builds and uploads wheels to PyPI automatically, macOS arm64 included. The pyodide.yml workflow does the same for the Pyodide wheel, and attaches it to the GitHub release.
Pin the C++ template to the new tag: GIT_TAG in _example_integration/CMakeLists.txt (the submodule pthom/imgui_bundle_template). Push the template, then commit the submodule’s new pointer in the bundle.

About cibuildwheel¶

cibuildwheel is a tool that builds Python wheels for multiple platforms and Python versions in a consistent, reproducible way. It:

Runs your build inside isolated environments (Docker on Linux, native on macOS/Windows)
Builds wheels for all supported Python versions (3.8–3.13+)
Handles platform-specific quirks (manylinux, musllinux, macOS universal2, etc.)
Is used both in CI (wheels.yml) and for manual local builds

The project’s cibuildwheel configuration is in pyproject.toml under [tool.cibuildwheel].

Manual build using cibuildwheel¶

To target specific Python versions:

CIBW_ARCHS_MACOS="arm64" CIBW_BUILD="cp311-* cp312-*" uv tool run cibuildwheel --platform=macos

To build for macOS 11 (disables FreeType): in pyproject.toml, change MACOSX_DEPLOYMENT_TARGET="14.0" to "11.0".

Upload wheels to PyPI:

uv tool run twine upload wheelhouse/*

Pyodide release¶

Since Pyodide 314 / pyodide-build 0.35, Pyodide wheels (platform tag pyemscripten_YYYY_P_wasm32, cf PEP 783) can be published on PyPI alongside the desktop wheels. micropip then installs them directly: micropip.install("imgui-bundle").

At a release, the pyodide.yml CI workflow builds the Pyodide wheel and uploads it to PyPI and to the GitHub release: nothing to do by hand. Before the release, check it locally:

Build locally: just pyodide_setup_local_build (once), then just pyodide_build.
Test in a browser: just pyodide_serve_projects, then open http://localhost:6456/pyodide_test_bundle/test_cdn_pyodide_local_wheel.html

Only if the CI’s upload failed, upload the local wheel by hand (it can be added to an existing release version): uv tool run twine upload dist/imgui_bundle-*pyemscripten*.whl.

See the Pyodide build guide for details on the build environment. Note: the legacy distribution channel (pyodide-recipes repository) is deprecated for imgui-bundle; the recipe there is disabled, so micropip falls through to PyPI.

Web checks before a release¶

The web builds are not covered by the test suite: check them by hand, in a browser, before tagging.

ImGui Bundle Explorer (Emscripten)

just ibex_build
just ibex_serve     # then open http://localhost:8642/demo_imgui_bundle.html

Try a few demos (for example the test engine and the docking demos).

ImGui Explorer (Emscripten)

just imex_ems_build
just imex_ems_serve     # then open http://localhost:7006/

Check that the Dear ImGui version displayed is the expected one.

Pyodide

just pyodide_build
just pyodide_serve_projects

Then open:

Page	Expected
http://localhost:6456/local_wheels/	Offers the wheel of the new version (see wheel filename references)
http://localhost:6456/playground/	The demos work; the intro page displays the new version
http://localhost:6456/min_pyodide_app/demo_heart.html	Works. It installs `imgui-bundle` from PyPI, so it displays the last released version until the new one is published: open it again after the release to check that PyPI serves the new wheel

Deploy: just cf_deploy_all_in_one, see Cloudflare deploy.

Third party renderers check¶

Some libraries render Dear ImGui by themselves, from Python: they walk ImDrawData, ImDrawList, ImDrawCmd and the texture requests (ImTextureData) through the bindings. They are the most sensitive users of these bindings, and nothing in this repository exercises them the same way: a member renamed or removed by an update of Dear ImGui breaks them at runtime (this happened with ImDrawData.cmd_lists_count in v1.92.900).

After an update of Dear ImGui, run one of them against the new wheel before tagging. For example wgpu-py, whose imgui renderer is based on imgui_bundle:

python -m venv venv_wgpu && source venv_wgpu/bin/activate
pip install wgpu rendercanvas glfw
pip install path/to/the/new/imgui_bundle-xxx.whl    # or: pip install -v . (from this repository)
git clone https://github.com/pygfx/wgpu-py.git
python wgpu-py/examples/imgui_basic_example.py        # any of the examples/imgui_*.py

Expected: the window shows the Gui (text, widgets, fonts), and reacts to the mouse and the keyboard. An AttributeError on a draw data / draw list / texture member means that the bindings changed under the renderer: restore the member (possibly as a read-only property), or warn the maintainers before the release.