microsoft / microsoft/onnxruntime
[Web] Deprecate the onnxruntime-web WebGL backend
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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