{"id":11493,"library":"onnxruntime-web","title":"ONNX Runtime Web","description":"ONNX Runtime Web (ORT Web) is a JavaScript library designed to execute ONNX (Open Neural Network Exchange) machine learning models directly within web browsers and Node.js environments. The current stable version is 1.24.3. The project maintains a regular release cadence, with patch releases frequently published between major quarterly releases, ensuring timely bug fixes, security enhancements, and performance updates. Key differentiators include its ability to run models client-side, reducing server-client communication and enhancing user privacy. It leverages WebAssembly (WASM) for efficient CPU execution and provides GPU acceleration through WebGL (in maintenance mode) and the more modern WebGPU (experimental, launched in v1.17). ORT Web supports a broad range of ONNX operators and offers optimizations for performance and memory usage, making it suitable for deploying various AI models like image classification, object detection, and generative AI directly in web applications.","status":"active","version":"1.24.3","language":"javascript","source_language":"en","source_url":"https://github.com/Microsoft/onnxruntime","tags":["javascript","ONNX","ONNXRuntime","ONNX Runtime","typescript"],"install":[{"cmd":"npm install onnxruntime-web","lang":"bash","label":"npm"},{"cmd":"yarn add onnxruntime-web","lang":"bash","label":"yarn"},{"cmd":"pnpm add onnxruntime-web","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ES6 module import is recommended. CommonJS `require` is also supported but less idiomatic for modern browser-focused development.","wrong":"const ort = require('onnxruntime-web');","symbol":"ort","correct":"import * as ort from 'onnxruntime-web';"},{"note":"Importing named exports directly for core components is standard. For specific execution providers like WebGPU, the import path changes, e.g., `import * as ort from 'onnxruntime-web/webgpu';` for the entire namespace.","wrong":"import { InferenceSession } from 'onnxruntime-web/webgpu';","symbol":"InferenceSession","correct":"import { InferenceSession, Tensor } from 'onnxruntime-web';"},{"note":"The `Tensor` class is a fundamental data structure. It's part of the main `onnxruntime-web` package.","wrong":"import { Tensor } from 'onnxruntime-web/webgpu';","symbol":"Tensor","correct":"import { Tensor } from 'onnxruntime-web';"},{"note":"Global environment settings (`ort.env`) should be accessed via the namespace import (`ort.*`). These settings often need to be configured before creating any inference sessions.","wrong":"import { env } from 'onnxruntime-web'; env.wasm.numThreads = 4;","symbol":"ort.env","correct":"import * as ort from 'onnxruntime-web'; ort.env.wasm.numThreads = 4;"}],"quickstart":{"code":"import * as ort from 'onnxruntime-web';\n\nconst runModel = async () => {\n  // Configure ONNX Runtime Web environment (optional, for performance)\n  // Enable WebAssembly SIMD for performance if supported\n  ort.env.wasm.simd = true;\n  // Set number of threads for WebAssembly (auto-detected if 0, 1 disables multithreading)\n  // Requires cross-origin isolation headers for multithreading in browsers.\n  ort.env.wasm.numThreads = Math.min(navigator.hardwareConcurrency / 2, 4) || 1; // Example setting\n\n  // Choose execution providers. WebGPU is experimental but offers best performance.\n  // Fallback to WASM (CPU) if WebGPU is not available.\n  const executionProviders = ['webgpu', 'wasm'];\n\n  // Load a sample ONNX model (e.g., a simple identity model from a public URL).\n  // In a real app, place your model.onnx in the 'public' folder or fetch from a CDN.\n  const modelPath = 'https://onnxruntime.ai/onnx-models/mnist-8.onnx'; // Example model\n\n  let session;\n  try {\n    session = await ort.InferenceSession.create(modelPath, { executionProviders });\n    console.log('Inference session created successfully.');\n  } catch (e) {\n    console.error(`Failed to create inference session: ${e.message}. Trying WASM only.`);\n    // Fallback if initial providers fail\n    session = await ort.InferenceSession.create(modelPath, { executionProviders: ['wasm'] });\n    console.log('Inference session created with WASM fallback.');\n  }\n\n  // Create a dummy input tensor for an MNIST model (28x28 grayscale image).\n  // Model expects input 'Input3' of shape [1, 1, 28, 28] and type 'float32'.\n  const inputData = new Float32Array(1 * 1 * 28 * 28).fill(0.5); // Example: fill with 0.5\n  const inputTensor = new ort.Tensor('float32', inputData, [1, 1, 28, 28]);\n\n  // Prepare input feeds, matching model's expected input names.\n  const feeds = { 'Input3': inputTensor };\n\n  // Run inference.\n  try {\n    const results = await session.run(feeds);\n\n    // Get output (model has one output 'Plus21_Output').\n    const outputTensor = results['Plus21_Output'];\n    console.log('Inference results:', outputTensor.data);\n    console.log('Output tensor type:', outputTensor.type);\n    console.log('Output tensor dimensions:', outputTensor.dims);\n  } catch (e) {\n    console.error(`Failed to run inference: ${e.message}`);\n  }\n};\n\nrunModel();","lang":"typescript","description":"This quickstart demonstrates how to initialize an ONNX Runtime Web session, configure execution providers, load a pre-trained ONNX model (MNIST example), create an input Tensor, run inference, and access the output results, including fallback strategies for execution providers."},"warnings":[{"fix":"Upgrade to `onnxruntime-web` v1.24.3 or newer immediately to mitigate known security risks. Regularly check for new patch releases.","message":"Multiple security vulnerabilities (heap out-of-bounds read/write, integer truncation) were fixed in patch releases like v1.24.3 and v1.24.2. Older versions are vulnerable to these issues, which could lead to arbitrary code execution or data leakage if processing maliciously crafted ONNX models.","severity":"breaking","affected_versions":"<=1.24.1"},{"fix":"Ensure your build environments and target devices for macOS/iOS adhere to the new minimum OS version (14.0+). Consider using pre-built artifacts if custom compilation causes issues.","message":"As of v1.24.1, ONNX Runtime (the core project, affecting underlying builds) no longer publishes x86_64 binaries for macOS/iOS, and the minimum macOS version supported is raised to 14.0. This may impact developers targeting older macOS/iOS versions or building custom WASM artifacts for these platforms.","severity":"breaking","affected_versions":">=1.24.1"},{"fix":"Configure your web server to send `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` headers for all resources, especially those serving your ONNX model and WASM files. Verify `self.crossOriginIsolated` is true in your browser's console.","message":"Multi-threading for WebAssembly (WASM) in browsers requires `SharedArrayBuffer` and `Atomics`, which in turn necessitates setting specific Cross-Origin Isolation headers (`Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`) on your web server. Without these headers, ONNX Runtime Web will silently fall back to single-threaded WASM, potentially impacting performance.","severity":"gotcha","affected_versions":">=1.8.0"},{"fix":"Ensure your web server (e.g., Nginx, Apache, or a bundler's dev server) is configured to serve `.wasm` files as `application/wasm` and `.mjs` files as `application/javascript`. For bundlers like Vite/Webpack, ensure the configuration properly handles these assets.","message":"The `onnxruntime-web` package's WASM files (`.wasm`, `.mjs`) must be served with correct MIME types by your web server (e.g., `application/wasm` for `.wasm`, `application/javascript` for `.mjs`). Incorrect MIME types can lead to `expected magic word 00 61 73 6d, found 3c 21 44 4f @+0` errors, indicating the browser is not correctly interpreting the WebAssembly binary.","severity":"gotcha","affected_versions":"*"},{"fix":"Prioritize `webgpu` in your `executionProviders` array (e.g., `['webgpu', 'wasm']`). Ensure target browsers support WebGPU and consider providing necessary cross-origin isolation headers for optimal performance.","message":"WebGL execution provider is in maintenance mode, and it is recommended to use WebGPU for better performance and broader operator coverage in modern browsers. WebGPU was officially launched in v1.17 and offers significant advantages for complex ML workloads.","severity":"deprecated","affected_versions":">=1.17.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that your web server serves `.wasm` files with the `application/wasm` MIME type and that `ort.env.wasm.wasmPaths` is correctly configured to point to the directory containing the WASM files. Ensure the WASM files are in your `public` folder or a location accessible by the browser.","cause":"The WebAssembly (`.wasm`) artifact is not being served correctly by the web server, or the URL configured for its path is incorrect. The browser received HTML or another file type instead of the WASM binary.","error":"Uncaught (in promise) Error: no available backend found. ERR: [wasm] Error: Aborted(CompileError: WebAssembly.instantiate(): expected magic word 00 61 73 6d, found 3c 21 44 4f @+0)"},{"fix":"Use ES module syntax: `import * as ort from 'onnxruntime-web';` and then `ort.InferenceSession.create(...)`. Alternatively, `import { InferenceSession } from 'onnxruntime-web';`. Ensure your build tool (Webpack, Rollup, Vite) is configured for ES modules.","cause":"Attempting to use `InferenceSession` (or `Tensor`, `env`, etc.) without a proper ES module import or when a CommonJS `require` call is expected but not handled by the build system.","error":"Uncaught ReferenceError: InferenceSession is not defined"},{"fix":"Inspect your ONNX model to determine the exact input tensor names. Tools like Netron can visualize the model graph and its input/output names. Ensure the keys in your `feeds` object (`await session.run(feeds)`) precisely match these names.","cause":"The name used for the input tensor in the `feeds` object does not match any of the expected input names defined in the ONNX model.","error":"[ONNXRuntimeError] : 2 : INVALID_ARGUMENT : Input 'input_name' is not found in the model"},{"fix":"Review the ONNX model's input signature (using Netron or similar tools) for the expected dimensions and data type. Ensure the `Tensor` you create (e.g., `new ort.Tensor(type, data, dims)`) exactly matches these specifications. Pay close attention to batch size (often the first dimension).","cause":"The shape (dimensions) or data type of an input `Tensor` provided to `session.run()` does not match the shape or data type expected by the ONNX model.","error":"[ONNXRuntimeError] : 2 : INVALID_ARGUMENT : Got invalid dimensions for input: input_name for the following indices index: X Got: Y Expected: Z"},{"fix":"Ensure `ort.InferenceSession.create()` is called only once per model or use a single, shared session instance. If using multiple models, manage their sessions carefully. This error can also stem from underlying WASM loading issues (e.g., incorrect `wasmPaths` or MIME types) which prevented the initial `initWasm()` call from succeeding.","cause":"This often occurs when trying to initialize a new ONNX Runtime Web session after a previous initialization attempt failed or was not properly cleaned up, or if multiple WASM execution environments are being initialized incorrectly within the same context.","error":"Failed to create inference session: Error: previous call to 'initWasm()' failed."}],"ecosystem":"npm"}