Implementation:Onnx Onnx Type Mapping

Knowledge Sources	Onnx_Onnx
Domains	Data Types, Type Conversion
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for mapping ONNX tensor data types to NumPy data types provided by the ONNX library.

Description

The onnx/_mapping.py module provides the central mapping between ONNX tensor data types (as defined in TensorProto) and their corresponding NumPy data types. It defines how tensor types are represented in memory and how they are stored in the TensorProto protocol buffer format.

The module defines a TensorDtypeMap named tuple with three fields: np_dtype (the NumPy dtype for in-memory representation), storage_dtype (the TensorProto field used for storage), and name (a human-readable string name). The main data structure is TENSOR_TYPE_MAP, a dictionary keyed by TensorProto type constants that maps to TensorDtypeMap instances.

The mapping handles special storage cases where multiple types share the same protobuf storage field. For example, INT8, UINT8, INT16, UINT16, BOOL, and FLOAT16 all use the int32_data field for storage. The module supports a comprehensive range of data types including standard types (float32, float64, int32, int64), specialized ML types (bfloat16, float8 variants such as FLOAT8E4M3FN and FLOAT8E5M2), sub-byte types (INT4, UINT4, INT2, UINT2), and the newest formats (FLOAT4E2M1, FLOAT8E8M0). Extended types rely on the ml_dtypes library for their NumPy dtype representations.

Usage

Use this module when you need to convert between ONNX TensorProto data types and NumPy arrays. It is foundational to helper functions such as those in onnx.numpy_helper and onnx.helper that perform tensor serialization and deserialization. Import TENSOR_TYPE_MAP to look up the NumPy dtype corresponding to an ONNX tensor element type, or to determine which protobuf storage field a given type uses.

Code Reference

Source Location

• Repository: Onnx_Onnx
• File: onnx/_mapping.py

Signature

class TensorDtypeMap(NamedTuple):
    np_dtype: np.dtype
    storage_dtype: int
    name: str

TENSOR_TYPE_MAP: dict[int, TensorDtypeMap] = {
    int(TensorProto.FLOAT): TensorDtypeMap(np.dtype("float32"), int(TensorProto.FLOAT), "TensorProto.FLOAT"),
    int(TensorProto.UINT8): TensorDtypeMap(np.dtype("uint8"), int(TensorProto.INT32), "TensorProto.UINT8"),
    int(TensorProto.INT8): TensorDtypeMap(np.dtype("int8"), int(TensorProto.INT32), "TensorProto.INT8"),
    # ... (25 entries total covering all ONNX tensor data types)
}

Import

from onnx._mapping import TENSOR_TYPE_MAP, TensorDtypeMap

I/O Contract

Inputs

Name	Type	Required	Description
key	int	Yes	A TensorProto data type constant (e.g., TensorProto.FLOAT, TensorProto.INT64)

Outputs

Name	Type	Description
TensorDtypeMap.np_dtype	np.dtype	The NumPy dtype used for in-memory representation of the tensor data
TensorDtypeMap.storage_dtype	int	The TensorProto type constant indicating which protobuf storage field to use
TensorDtypeMap.name	str	Human-readable string name of the type (e.g., "TensorProto.FLOAT")

Usage Examples

from onnx._mapping import TENSOR_TYPE_MAP
from onnx.onnx_pb import TensorProto

# Look up the NumPy dtype for a FLOAT tensor
entry = TENSOR_TYPE_MAP[int(TensorProto.FLOAT)]
print(entry.np_dtype)       # float32
print(entry.storage_dtype)  # 1 (TensorProto.FLOAT)
print(entry.name)           # "TensorProto.FLOAT"

# Look up the storage type for INT8 (stored in int32_data)
entry = TENSOR_TYPE_MAP[int(TensorProto.INT8)]
print(entry.np_dtype)       # int8
print(entry.storage_dtype)  # 6 (TensorProto.INT32)

# Look up a specialized ML type
entry = TENSOR_TYPE_MAP[int(TensorProto.BFLOAT16)]
print(entry.np_dtype)       # bfloat16 (from ml_dtypes)

Related Pages

• Environment:Onnx_Onnx_Python_Runtime_Environment