microsoft / microsoft/onnxruntime

[Web] Deprecate the onnxruntime-web WebGL backend

Open
#32,241 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

ep:WebGPU platform:web
Dominant language
C++
Stars
21.9k
Forks
4.2k
Avg merge
4d 11h
Merged PRs (30d)
184

Description

## Summary

The legacy WebGL backend in `onnxruntime-web` is deprecated and planned for removal in a subsequent release. This
issue is the authoritative migration guide and feedback channel for consumers that still rely on WebGL.

## Current status

This table will be updated as the deprecation progresses:

| Milestone | Status | Relevant change |
|---|---|---|
| Phase 1: deprecation warning and migration docs | In progress | PR/commit TBD |
| Deprecation release | Not released | Version and release notes TBD |
| Phase 2: WebGL removal | Not scheduled | PR/commit TBD |
| Removal release | Not scheduled | Version and release notes TBD |

Phase 2 is planned for a subsequent release. The schedule may be extended if WebGL-dependent consumers report
migration blockers here.

## Phase 1 behavior

The initial deprecation phase does **not** change inference behavior:

- `executionProviders: ['webgl']` continues to select WebGL.
- `import 'onnxruntime-web/webgl'` and the `ort.webgl.*` bundles remain available.
- Explicit WebGL use will emit a warning once, subject to `ort.env.logLevel`.
- WebGL remains opt-in and is not selected as a default fallback.

## Why WebGL is being removed

The WebGL backend originated in the standalone ONNX.js project and predates ONNX Runtime's WebAssembly
implementation. It is now in maintenance mode, supports fewer operators than WebGPU and WASM, and has behavioral
and floating-point differences from newer backends. Removing it will reduce duplicate maintenance and simplify the
`onnxruntime-web` build matrix.

## Migration options

### WebGPU

Use WebGPU where the target browsers support it:

```js
import * as ort from 'onnxruntime-web/webgpu';

const session = await ort.InferenceSession.create(model, {
executionProviders: ['webgpu'],
});
```

### WebAssembly/CPU

Use WASM when WebGPU is unavailable or broader browser compatibility is required:

```js
import * as ort from 'onnxruntime-web/wasm';

const session = await ort.InferenceSession.create(model);
```

The default `onnxruntime-web` import also uses WASM/CPU when no `executionProviders` option is specified. The
`onnxruntime-web/wasm` import explicitly selects the CPU-only bundle.

There will be no automatic redirect from WebGL. The WebGL-only bundle has no WASM fallback, and silently redirecting
to WebGPU would fail on browsers without `navigator.gpu` and could introduce hidden operator or numerical behavior
changes.

## Feedback requested

If you cannot migrate to WebGPU or WASM, please describe:

- the browser/platform that requires WebGL;
- the model or operators involved;
- the WebGPU or WASM failure, compatibility gap, or performance blocker;
- any release-timing constraint we should consider.

Design:
https://github.com/microsoft/onnxruntime/blob/main/docs/design/onnxruntime_web_remove_webgl_backend.md

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs/design/onnxruntime_web_remove_webgl_backend.md and review the issue's Phase 1 behavior and migration options. Identify the implementation and documentation entry points for the deprecation warning, bundle availability, and eventual WebGL removal; completion depends on the unspecified release and removal milestones being defined.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, wasm
Domain
machine-learning, web-dev
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.