[onnxruntime-web] Plans to deprecate and remove WebGL and JSEP by edgchen1 · Pull Request #29716 · microsoft/onnxruntime

edgchen1 · 2026-07-14T19:51:06Z

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.

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>

Copilot

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 and onnxruntime-web/webgl bundle.
Add a design proposal to migrate default WebGPU/WebNN from JSEP to the native WebGPU EP, including a one-release /jsep escape 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).

edgchen1 · 2026-07-14T20:03:33Z

FYI, @xenova @sushraja-msft

any feedback would be appreciated.

xenova · 2026-07-14T23:29:10Z

SGTM ✅ Transformers.js no longer uses either of these execution providers 👍

- 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>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

+**Related work:**
+[Migrate onnxruntime-web WebGPU/WebNN from JSEP to the native WebGPU EP](onnxruntime_web_jsep_to_webgpu_ep_migration.md)
+— independent, but shares the `onnxruntime-web/all` bundle and the deprecation-warning utility (see §5–§6).


+
+### 5.2 Warning placement
+
+The warning fires in `OnnxjsBackend` (`js/web/lib/backend-onnxjs.ts`), in `init()` /


+Backend choice is a **build-time** decision, not a runtime toggle. It is gated by `BUILD_DEFS` flags baked into
+each bundle at build time:


+   prominent release-notes/CHANGELOG entry (WASM filename `.jsep.wasm` → `.asyncify.wasm`, `/jsep` pin
+   instructions). Call out that **WebNN** in `.` / `/all` also moves from JSEP-hosted to native WebNN (the same
+   path `/webgpu` already ships), so WebNN users know to re-test and use `/jsep` on regression — the
+   WebGPU-centric framing otherwise hides this second swap (§7.3).


+   under `wasm.proxy = true` (§7.1); both `'gpu-buffer'` and `'ml-tensor'` IO-binding zero-copy handoff (§7.2);
+   native WebNN validated separately (§7.3); and the global `env.webgpu.*` settings gap (§7.4) closed by wiring


+| Proxy-worker path behaves differently | Unknown | **Investigate before flip** (§7.1) |
+| IO-binding (gpu-buffer/ml-tensor) semantics differ | Unknown | **Investigate before flip** (§7.2) |
+| WebNN behavior changes under native path | Unknown | Validate native WebNN separately (§7.3) |
+| Global `env.webgpu.*` settings (adapter/powerPreference/forceFallbackAdapter/profiling) silently dropped on native | Medium | Wire into the native path or document dropped/changed settings with migration guidance — release gate (§7.4, §8) |


edgchen1 and others added 5 commits July 10, 2026 17:50

edgchen1 requested a review from Copilot July 14, 2026 19:51

Copilot started reviewing on behalf of edgchen1 July 14, 2026 19:52 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Comment thread docs/design/onnxruntime_web_remove_webgl_backend.md Outdated

edgchen1 requested review from hariharans29, prathikr and qjia7 July 14, 2026 22:46

hariharans29 previously approved these changes Jul 15, 2026

View reviewed changes

qjia7 reviewed Jul 15, 2026

View reviewed changes

Comment thread docs/design/onnxruntime_web_jsep_to_webgpu_ep_migration.md

qjia7 reviewed Jul 15, 2026

View reviewed changes

Comment thread docs/design/onnxruntime_web_jsep_to_webgpu_ep_migration.md Outdated

edgchen1 dismissed hariharans29’s stale review via a358c0a July 15, 2026 17:48

edgchen1 requested review from Copilot, hariharans29 and qjia7 July 15, 2026 17:49

Copilot started reviewing on behalf of edgchen1 July 15, 2026 17:50 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[onnxruntime-web] Plans to deprecate and remove WebGL and JSEP#29716

[onnxruntime-web] Plans to deprecate and remove WebGL and JSEP#29716
edgchen1 wants to merge 6 commits into
mainfrom
edgchen1/ort_web_backend_deprecation_plans

edgchen1 commented Jul 14, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

edgchen1 commented Jul 14, 2026

Uh oh!

xenova commented Jul 14, 2026

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		### 5.2 Warning placement

		The warning fires in `OnnxjsBackend` (`js/web/lib/backend-onnxjs.ts`), in `init()` /

		Backend choice is a build-time decision, not a runtime toggle. It is gated by `BUILD_DEFS` flags baked into
		each bundle at build time:

		under `wasm.proxy = true` (§7.1); both `'gpu-buffer'` and `'ml-tensor'` IO-binding zero-copy handoff (§7.2);
		native WebNN validated separately (§7.3); and the global `env.webgpu.*` settings gap (§7.4) closed by wiring

Uh oh!

Conversation

edgchen1 commented Jul 14, 2026

Description

Motivation and Context

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

edgchen1 commented Jul 14, 2026

Uh oh!

xenova commented Jul 14, 2026

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants