Building for WebAssembly
PythonSCAD can be compiled to WebAssembly with Emscripten, producing a headless build that runs the geometry kernel and an embedded CPython interpreter directly in the browser. This powers the in-browser Playground.
If you only want to try PythonSCAD in your browser, you do not need to build anything — just open the Playground. This page is for contributors who want to build or hack on the WASM bundle.
Prerequisites
The build runs inside Docker so you do not need a host Emscripten/CPython toolchain. You need Docker and a checkout of the repository (with submodules).
There are two build variants:
node— runs under Node.js with direct filesystem access; used for fast smoke tests (renders an STL via the command line).web— the browser bundle (pythonscad.js+pythonscad.wasm+pythonscad.data) loaded as an ES module.
Build
# Show the content-derived identity used for the public toolchain image.
./scripts/wasm-toolchain-id.sh
# Node variant (smoke test). The helper pulls the matching public toolchain
# image, or builds it locally when the current inputs have not been published.
./scripts/wasm-base-docker-run.sh emcmake cmake -B build-wasm-node \
-DWASM_BUILD_TYPE=node -DCMAKE_BUILD_TYPE=Release -DEXPERIMENTAL=1
./scripts/wasm-base-docker-run.sh cmake --build build-wasm-node -j"$(nproc)"
node build-wasm-node/pythonscad.js -o out.stl --trust-python script.py
# Web variant (browser bundle)
./scripts/wasm-base-docker-run.sh emcmake cmake -B build-wasm-web \
-DWASM_BUILD_TYPE=web -DCMAKE_BUILD_TYPE=Release -DEXPERIMENTAL=1
./scripts/wasm-base-docker-run.sh cmake --build build-wasm-web -j"$(nproc)"
Testing the web build locally
Browsers require the right MIME types for .wasm (application/wasm) and the
preloaded .data package, so a plain python3 -m http.server will not work.
Use the bundled dev server, which sets the correct types:
cp wasm-test/test.html wasm-test/notebook.html build-wasm-web/
mkdir -p build-wasm-web/vendor
cp wasm-test/vendor/three.module.min.js wasm-test/vendor/three.core.min.js build-wasm-web/vendor/
python3 wasm-test/serve.py 8080 build-wasm-web/
# Open http://localhost:8080/test.html or /notebook.html
test.html exercises the command-line export path; notebook.html is the
interactive notebook (the same page served as the Playground).
JavaScript API
To embed PythonSCAD in your own page, see the Browser / WASM API reference.
More detail
The full build guide — base-image internals, the node vs web rationale,
JSPI/MAIN_MODULE notes, and known gotchas — lives in the developer docs at
doc/wasm-build.md.