ONNX Runtime JavaScript Common API

1.24.3 · active · verified Sun Apr 19

onnxruntime-common serves as the foundational JavaScript API layer for the ONNX Runtime ecosystem, providing shared types, interfaces, and core functionalities. It is designed to be consumed indirectly by platform-specific packages like `onnxruntime-node`, `onnxruntime-web`, and `onnxruntime-react-native`, rather than being used directly by end-user applications. The current stable version is 1.24.3, with frequent patch releases addressing bug fixes, security enhancements, and execution provider updates, as evidenced by recent 1.24.x versions. Its primary differentiator is enabling a consistent programming model across various JavaScript environments, abstracting away platform-specific implementations and ensuring interoperability for machine learning inference.

Common errors

```
Module not found: Can't resolve 'onnxruntime-common' in '...' or similar import errors
```
cause Attempting to directly import from `onnxruntime-common` without having it installed, or more commonly, trying to use it as a primary entry point for ONNX Runtime functionality.

fix Install the correct platform-specific ONNX Runtime package (e.g., `npm install onnxruntime-node`) and adjust your imports to use that package directly (e.g., `import * as ort from 'onnxruntime-node';`).
```
TypeError: ort.InferenceSession.create is not a function
```
cause Attempting to call static methods like `create` directly on the `InferenceSession` symbol imported from `onnxruntime-common`. The common package often defines interfaces or abstract classes, not concrete implementations with static factory methods.

fix Ensure you are importing and calling `create` from the platform-specific package's `InferenceSession` implementation (e.g., `import * as ort from 'onnxruntime-node'; const session = await ort.InferenceSession.create('model.onnx');`).
```
Error: ONNX Runtime requires an execution provider. Please ensure you have enabled at least one.
```
cause While `onnxruntime-common` doesn't directly cause this, it's a common error that propagates from platform-specific packages if no valid execution provider (e.g., WASM, WebGPU, CPU, CUDA) is found or explicitly configured during session creation.

fix When creating an `InferenceSession`, pass `sessionOptions` to explicitly define execution providers, for example: `{ executionProviders: ['webgpu', 'wasm'] }` for web or `{ executionProviders: ['cuda', 'cpu'] }` for Node.js.

Warnings

breaking Python 3.10 wheels are no longer published for ONNX Runtime. Users must upgrade their Python environment to 3.11+ when using Python bindings. Python 3.14 support has been added.
Fix: Upgrade Python environments to version 3.11 or newer to ensure compatibility with ONNX Runtime Python packages.
breaking x86_64 binaries for macOS/iOS are no longer provided, and the minimum macOS version supported for ONNX Runtime has been raised to 14.0.
Fix: Ensure development and deployment environments for macOS/iOS target ARM64 architecture and run macOS 14.0 (Sonoma) or newer.
breaking ONNX Runtime GPU packages now explicitly require CUDA 12.x. Packages built for CUDA 11.x are no longer published, potentially breaking existing setups.
Fix: Update CUDA toolkit, drivers, and related dependencies to version 12.x or higher when utilizing GPU execution providers.
breaking The minimum supported Windows version for ONNX Runtime has been raised to 10.0.19041 (Windows 10, version 20H1).
Fix: Ensure target Windows machines are running OS Build 10.0.19041 or newer to avoid compatibility issues.
gotcha This `onnxruntime-common` package is designed as a shared API layer and is not intended for direct use. End-user applications should install and depend on platform-specific packages.
Fix: For Node.js, install `onnxruntime-node`. For browsers, use `onnxruntime-web`. For React Native, use `onnxruntime-react-native`. Import core functionality from these specific packages.
breaking Critical security vulnerabilities, including heap out-of-bounds read/write issues in `GatherCopyData` and `RoiAlign`, were fixed in version 1.24.3.
Fix: Immediately upgrade to `onnxruntime-common@1.24.3` or a newer version to apply essential security patches and prevent potential exploits.

Install

npm install onnxruntime-common npm
yarn add onnxruntime-common yarn
pnpm add onnxruntime-common pnpm

Imports

InferenceSession
```
import { InferenceSession } from 'onnxruntime-common';
```
Common interface/class for inference sessions, typically instantiated via platform-specific packages (e.g., `onnxruntime-node`).
Tensor
```
import { Tensor } from 'onnxruntime-common';
```
Represents a multi-dimensional array, the fundamental data structure for model inputs and outputs across all ONNX Runtime JavaScript environments.
SessionOptions
```
import { SessionOptions } from 'onnxruntime-common';
```
Interface for configuring an InferenceSession, including execution providers, logging, and other runtime parameters. Used when creating a session with platform-specific `create()` methods.

view raw JSON →