Environment:Microsoft Onnxruntime Python Inference Environment

Field	Value
sources	setup.py, requirements.txt, onnxruntime/__init__.py
domains	inference, python, machine-learning
last_updated	2026-02-10

Overview

The standard CPython environment for running ONNX model inference using the onnxruntime package on CPU or GPU across Linux, Windows, and macOS.

Description

The Python Inference Environment provides everything needed to load and execute ONNX models through the onnxruntime Python package (version 1.25.0). It wraps the high-performance C++ ONNX Runtime engine via pybind11 bindings, exposing the InferenceSession API that accepts NumPy arrays as input and returns NumPy arrays as output. The environment targets Python 3.10 and above, with official classifier support for Python 3.11, 3.12, 3.13, and 3.14. On Linux it ships as manylinux2014-compatible wheels, ensuring broad compatibility across distributions. Core runtime dependencies are intentionally minimal: flatbuffers for serialization, numpy (>= 1.21.6) for tensor I/O, packaging for version utilities, protobuf for model format support, and sympy for symbolic shape inference.

Usage

Use this environment whenever you need to:

Run inference on a pre-trained ONNX model from Python.
Integrate ONNX Runtime into a Python application, web service, or data pipeline.
Benchmark or validate ONNX model outputs against reference implementations.
Perform CPU-based inference without any GPU dependencies.

System Requirements

Requirement	Minimum	Recommended
Python	3.10	3.12
Operating System	Linux (manylinux2014), Windows, macOS	Linux x86_64
Architecture	x86_64, aarch64	x86_64
RAM	2 GB	8 GB+ (model dependent)
Disk	200 MB (package)	500 MB+ (with models)

Dependencies

System Packages

No additional system packages are required for the CPU-only wheel. The manylinux2014 wheels bundle all necessary native libraries. On macOS and Windows the pre-built wheels are self-contained.

Python Packages

Package	Version Constraint	Purpose
numpy	>= 1.21.6	Tensor input/output as ndarrays
flatbuffers	(latest)	ORT format model deserialization
protobuf	(latest)	ONNX protobuf model loading
packaging	(latest)	Version parsing and comparison
sympy	(latest)	Symbolic shape inference

Credentials

No credentials or API keys are required. The following environment variables may optionally influence behavior:

Variable	Purpose	Required
`ORT_CUDA_UNAVAILABLE`	When set, suppresses CUDA provider registration even if CUDA libraries are present (setup.py L180)	No

Quick Install

pip install onnxruntime==1.25.0

To install with all core dependencies explicitly:

pip install onnxruntime==1.25.0 numpy>=1.21.6 flatbuffers protobuf packaging sympy

Code Evidence

Python version requirement (setup.py:877)

# setup.py:877
python_requires=">=3.10",

This line in the setup() call enforces that the package cannot be installed on Python versions below 3.10.

Supported Python classifiers (setup.py:629-632)

# setup.py:629-632
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Programming Language :: Python :: 3.14",

These PyPI classifiers declare official support for Python 3.11 through 3.14.

Package version (init.py:13)

# onnxruntime/__init__.py:13
__version__ = "1.25.0"

manylinux2014 platform tags (setup.py:96-122)

# setup.py:96-122
# Platform-specific wheel naming uses manylinux2014 tags
# to ensure compatibility with glibc 2.17+ Linux distributions.

Common Errors

Error	Cause	Solution
`RuntimeError: python_requires >= 3.10`	Installing on Python 3.9 or earlier	Upgrade to Python 3.10 or later: `pyenv install 3.12`
`ImportError: numpy >= 1.21.6 is required`	numpy version too old	Run `pip install --upgrade numpy>=1.21.6`
`ModuleNotFoundError: No module named 'onnxruntime'`	Package not installed in active environment	Verify virtual environment is activated and run `pip install onnxruntime`
`InvalidGraph: node output type mismatch`	ONNX model was exported with incompatible opset	Re-export model with a supported opset or upgrade onnxruntime
`ONNXRuntimeError: [ONNXRuntimeError] FAIL`	Input tensor shape or dtype does not match model expectations	Verify input shapes and dtypes using `session.get_inputs()`

Compatibility Notes

Linux: Wheels are built against manylinux2014 (glibc 2.17+). This covers most modern distributions including Ubuntu 18.04+, CentOS 7+, and Debian 10+.
Windows: Pre-built wheels are available for x86_64. Visual C++ Redistributable 2019 or later may be required at runtime.
macOS: Supports both Intel (x86_64) and Apple Silicon (arm64) via universal2 or platform-specific wheels.
Python 3.10: Minimum supported version. Earlier versions (3.8, 3.9) are no longer supported as of onnxruntime 1.25.0.
NumPy 2.x: Compatible with NumPy 2.0+ while maintaining backward compatibility with NumPy 1.21.6+.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment