[onnxruntime-web] Plans to deprecate and remove WebGL and JSEP - #29716
Merged
Edward Chen (edgchen1) merged 10 commits intoAug 4, 2026
Conversation
Add two design documents under docs/design/ covering the plan to consolidate onnxruntime-web on the native WebGPU execution provider: - onnxruntime_web_jsep_to_webgpu_ep_migration.md: migrate WebGPU/WebNN from the JSEP TypeScript compute path to the native WebGPU EP, with a transparent default swap, a temporary /jsep escape hatch, int64 analysis, and pre-flip parity investigation items. - onnxruntime_web_remove_webgl_backend.md: deprecate and remove the legacy WebGL (onnxjs) backend, with explicit (non-transparent) removal and current WebGPU browser-coverage context. Both docs use a two-phase (deprecate, then remove) approach, adopt clean removal without tombstone shims, and point consumers at a single canonical tracking issue. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Revise the onnxruntime-web backend consolidation design docs per review comments: - WebGL removal doc: reword the WebGPU browser-coverage section to reflect MDN's partial support with platform caveats (Chrome Linux GPU-gen limits; Firefox 141 excluding Linux and Intel Macs) instead of implying universal availability, and revert the fallback-risk likelihood to Medium. - WebGL removal doc: drop the paragraph about the ['webgl','wasm'] case, since the existing resolveBackendAndExecutionProviders warning already covers it and no special handling is needed. - JSEP migration doc: tighten the Phase 2 release gate to explicitly require resolving the Section 7 blockers (proxy-worker, gpu-buffer/ml-tensor IO binding, native WebNN) with targeted coverage, in addition to running the default-bundle suite against the native EP. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Condense both the JSEP -> native WebGPU EP migration and the WebGL removal design docs, trimming the derivation narrative while preserving the settled decisions and rationale. Collapse the int64 analysis subsections into a single section, reduce the open-investigation source/runtime status to concise lines, and reframe the removal-ergonomics sections around what each phase does rather than what it omits. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…ion docs Make the /all bundle convergence order-independent across both design docs: the JSEP->native flip and the WebGL removal are independent efforts that may land in either order or different releases, and /all collapses into a single physical alias only once both have landed (whichever lands second performs the repoint). Also: elevate the global env.webgpu.* settings parity gap to a prerequisite (JSEP open item, release gate, and risk row); correct the WebGPU browser-coverage table to MDN's current data (Chrome/Edge full from 144); fold the WebGL deprecation-window decision into the Phase 2 section; drop the Status: Draft lines and the redundant Resolved-decisions sections; and align Phase 2 wording (subsequent release). Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Mirror the WebGL doc: note the single-release default for the /jsep escape hatch and that extension is driven by native-EP parity regressions surfacing via /jsep fallback usage, not a fixed calendar. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds two design documents to communicate the planned deprecation/removal path for legacy browser backends in onnxruntime-web, with the intent to standardize on the native WebGPU execution provider and simplify the build/export matrix.
Changes:
- Add a design proposal to deprecate then remove the legacy WebGL (
onnxjs) backend andonnxruntime-web/webglbundle. - Add a design proposal to migrate default WebGPU/WebNN from JSEP to the native WebGPU EP, including a one-release
/jsepescape hatch.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/design/onnxruntime_web_remove_webgl_backend.md | New design doc outlining rationale, phased plan, and migration guidance for removing the WebGL backend. |
| docs/design/onnxruntime_web_jsep_to_webgpu_ep_migration.md | New design doc outlining phased migration from JSEP to the native WebGPU EP (plus escape hatch and parity investigation items). |
Contributor
Author
|
FYI, Joshua Lochner (@xenova) Sushanth Rajasankar (@sushraja-msft) any feedback would be appreciated. |
Edward Chen (edgchen1)
requested review from
Hariharan Seshadri (hariharans29),
Prathik Rao (prathikr) and
Jiajia Qin (qjia7)
July 14, 2026 22:46
Contributor
|
SGTM ✅ Transformers.js no longer uses either of these execution providers 👍 |
Hariharan Seshadri (hariharans29)
previously approved these changes
Jul 15, 2026
- WebGPU coverage table (WebGL doc 4.1): switch from pinned MDN 'full support' versions to qualitative status, note WebGPU has shipped by default in Chrome/Edge since 113, keep Firefox as plain 'partial' (no roadmap claim), and link MDN api.GPU as the live source (per Copilot reviewer). - Migration guide (JSEP doc 11): add guidance to prefer onnxruntime-web/jspi on JSPI-capable browsers for a smaller WASM and lower per-call overhead, with Asyncify as the universal fallback (per qjia7). - int64 gap (JSEP doc 6): replace the misleading 'CPU-fallback cost' phrasing with the actual cost (CPU/WASM execution of int64-input ops plus partition-boundary copies; no GPU-to-CPU download of int64 data) (per qjia7). - Remove the Last updated field from both docs. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Edward Chen (edgchen1)
requested review from
Copilot,
Hariharan Seshadri (hariharans29) and
Jiajia Qin (qjia7)
July 15, 2026 17:49
Rewrite both design docs to read as clean decision docs rather than a record of the review discussion: drop meta-labels (verified/resolved/red herring), collapse repeated justifications, condense the int64 and open-items sections, and trim the risk tables and migration guides. Keep all concrete technical facts (file names, BUILD_DEFS flags, config keys, phased plan) and fix cross-references after collapsing subsections. Also refine the int64 framing: drop the 'never a regression / enhancement' verdict and describe enableInt64=1 as an opt-in speed/precision tradeoff (lossy for genuine > 2^31 values). Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…ign docs Refine the JSEP-to-native-WebGPU-EP migration doc and the WebGL removal doc based on PR review feedback: correct the build-config/CI-coverage claims (the default and ./webgpu bundles are the same build; proxy, IO-binding, and WebNN are unexercised against the native EP in CI rather than differing), fix the WASM artifact suffix mapping, and tighten the validation items and release gate. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Address further PR review feedback: WebNN is already the native C++ WebNN EP in both the JSEP and native-WebGPU builds, so the migration only removes JSEP's shared init glue (jsepInit -> webnnInit, same WebNNBackend) rather than moving WebNN to a native host. Restrict the native-WebGPU-EP migration language to WebGPU throughout, and drop the deprecation banner from the generated webgpu-operators.md (guidance stays in the hand-authored README). Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Jiajia Qin (qjia7)
approved these changes
Aug 4, 2026
This was referenced Aug 14, 2026
Open
This was referenced Aug 21, 2026
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Add plans for deprecating and removing JSEP and WebGL in onnxruntime-web. The native WebGPU EP should be the preferred path going forward.
Motivation and Context
Share plans and get feedback before implementation.