Hugging Face's logo

executorch-community
/
ExecuTorch-WebGPU-Runtime

ExecuTorch
webgpu
webassembly
browser
Model card Files
xet
 Community
ExecuTorch-WebGPU-Runtime / BUILD_INFO.md
psiddh's picture
psiddh
Build notes: both upstream changes are merged
ebf0ed9 verified
preview code
|
Raw History Blame Contribute Delete
4.49 kB

ExecuTorch Wasm + WebGPU runtime

executorch_wasm_lib.js and executorch_wasm_lib.wasm are the ExecuTorch Wasm bindings (extension/wasm) with the WebGPU backend, linked into one web bundle. The .js loader ships in this folder. The .wasm is hosted on Hugging Face (executorch-community/ExecuTorch-WebGPU-Runtime, pinned in src/config/runtime.js), downloaded and checked against the sha256 below like a model file. Every demo in the playground shares this one runtime (src/runtime/executorch.js). The JS file defines createExecuTorch(). After await et.initWebGPU(), a .pte loads with et.Module.load(path) and loadMethod('forward'), and runs with an async forward([tensors]).

Source

Built from the ExecuTorch source tree of 2026-10-16 (version.txt 1.6.0) with the two changes that make WebGPU run in the Wasm build, both merged upstream:

  1. pytorch/executorch#23938: the EXECUTORCH_BUILD_WASM_WEBGPU option, which links the WebGPU backend into extension/wasm, and the initWebGPU() binding.
  2. pytorch/executorch#23914: WebGPUGraph::propagate_resize resizes every operand before its consumer in one pass, so a multi-token LLM prefill works.

A build from ExecuTorch main that contains both, with the commands below, should give the same files. The emdawnwebgpu override (EXECUTORCH_WEBGPU_EMDAWNWEBGPU_PORT) was only needed because the build machine could not reach GitHub; without it, Emscripten downloads the same emdawnwebgpu version itself.

Toolchain

  • Emscripten 4.0.19, official release build 8b01e2ec3f33e6b94842096d7312ce4ef5f33f6c.
  • emdawnwebgpu v20251002.162335, the version Emscripten 4.0.19 pins. It was rebuilt from Dawn source at 01940842b667a7812d0e4ca0ef4367fbec294241, using Dawn's own packaging recipe.
  • CMake 3.31, Ninja 1.13. The configure step needs a Python with torch (for torchgen).

Build

A small consumer project links the bindings into a distributable bundle, as described under "Building for Web" in extension/wasm/README.md:

cmake_minimum_required(VERSION 3.29)
project(executorch_web)
add_subdirectory(${ET_SRC} executorch)
add_executable(executorch_wasm_lib)
target_link_libraries(executorch_wasm_lib PRIVATE executorch_wasm)
target_link_options(executorch_wasm_lib PRIVATE
  -sMODULARIZE=1 -sEXPORT_NAME=createExecuTorch -sENVIRONMENT=web,worker
  -sFORCE_FILESYSTEM=1 -sEXPORTED_RUNTIME_METHODS=FS -sINITIAL_MEMORY=64MB
  -sEXPORT_EXCEPTION_HANDLING_HELPERS=1)

emcmake cmake -S <consumer project> -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DET_SRC=<executorch> \
  -DEXECUTORCH_BUILD_WASM=ON -DEXECUTORCH_BUILD_WEBGPU=ON -DEXECUTORCH_BUILD_WASM_WEBGPU=ON \
  -DEXECUTORCH_BUILD_EXTENSION_DATA_LOADER=ON -DEXECUTORCH_BUILD_EXTENSION_FLAT_TENSOR=ON \
  -DEXECUTORCH_BUILD_EXTENSION_MODULE=ON -DEXECUTORCH_BUILD_EXTENSION_NAMED_DATA_MAP=ON \
  -DEXECUTORCH_BUILD_EXTENSION_TENSOR=ON \
  -DEXECUTORCH_ENABLE_LOGGING=ON -DEXECUTORCH_LOG_LEVEL=Info \
  -DEXECUTORCH_WEBGPU_EMDAWNWEBGPU_PORT=<emdawnwebgpu_pkg>/emdawnwebgpu.port.py \
  "-DCMAKE_C_FLAGS=-ffile-prefix-map=<executorch>=executorch" \
  "-DCMAKE_CXX_FLAGS=-ffile-prefix-map=<executorch>=executorch" \
  -DPYTHON_EXECUTABLE=<python with torch>
cmake --build build --target executorch_wasm_lib

The WebGPU Wasm option itself adds -sASYNCIFY -sASYNCIFY_STACK_SIZE=65536 -sALLOW_MEMORY_GROWTH=1 -sMAXIMUM_MEMORY=4GB -fexceptions. The full portable kernel library is linked (no selective build). Logging is at Info, so a failed load or run prints the reason to the console. -ffile-prefix-map keeps build-machine paths out of the binary.

Files

File Bytes sha256
executorch_wasm_lib.js 165,877 8a631b1537927f8f2ef184d9f1b343061f47df0a32ddb8f5190d74e80d40618e
executorch_wasm_lib.wasm 6,562,188 35a9087d0b6cd86c279e7111adfd54a58156bd993928b20f63348f1043652eb4

Checked with this build

Headless Chromium 141, WebGPU on SwiftShader (no shader-f16), with the playground's models compared against ExecuTorch CPU references:

  • Depth Anything V2 Small, MODNet, Real-ESRGAN, D-FINE S: max abs difference between 0 and 4.6e-3.
  • SAM 2.1 Hiera Tiny: mask IoU 1.000 on a click, a second click, and a box prompt.

The playground's own end-to-end checks, through the real UI, cover Qwen3 0.6B, Llama 3.2 1B, SAM 2.1, Depth Anything V2, D-FINE S and Whisper base. Real GPUs and the shader-f16 kernel paths have not been tested with this build.