Implementation:Onnx Onnx Model Hub

Knowledge Sources	Onnx_Onnx
Domains	Model Management, Model Zoo, Download Client
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for discovering, downloading, caching, and loading pre-trained ONNX models from the ONNX model zoo, provided by the ONNX library.

Description

The hub.py module implements the ONNX Model Hub client, providing a programmatic interface for accessing pre-trained models from the official ONNX model zoo (github.com/onnx/models) or custom repositories. It provides a similar experience to PyTorch Hub or TensorFlow Hub for ONNX models.

The module centers around the ModelInfo class, which encapsulates model metadata including name, path, SHA256 digest, tags, and opset version. Model discovery works by fetching an ONNX_HUB_MANIFEST.json file from the target GitHub repository, which lists all available models and their properties.

The caching system stores downloaded models in a configurable directory. By default this is ~/.cache/onnx/hub, but it can be overridden via the ONNX_HOME or XDG_CACHE_HOME environment variables, or by calling set_dir(). When a model's SHA256 is available, it is prepended to the filename to enable cache invalidation when models are updated.

The load() function is the primary entry point. It discovers a model by name and optionally by opset version, downloads it via GitHub LFS media URLs if not already cached, verifies the SHA256 checksum, and returns a loaded ModelProto. Security warnings are displayed when downloading from untrusted (non-onnx/models) repositories.

The download_model_with_test_data() function downloads model archives (tar.gz) that include test data alongside the model, extracting them safely using onnx.utils._extract_model_safe.

The load_composite_model() function enables building composite models that combine a preprocessing model with a network model. It handles opset version alignment between the two models using the ONNX version converter, then merges them via onnx.compose.merge_models with IO mapping.

Usage

Use this module when you need to programmatically access pre-trained ONNX models for benchmarking, testing, transfer learning, or inference. It is particularly useful in automation scripts, CI/CD pipelines, and tutorials where models need to be downloaded on demand. The caching system ensures that repeated access is efficient.

Code Reference

Source Location

• Repository: Onnx_Onnx
• File: onnx/hub.py
• Lines: 1-480

Signature

class ModelInfo:
    def __init__(self, raw_model_info: dict[str, Any]) -> None: ...

def set_dir(new_dir: str) -> None: ...
def get_dir() -> str: ...

def list_models(
    repo: str = "onnx/models:main",
    model: str | None = None,
    tags: list[str] | None = None,
) -> list[ModelInfo]: ...

def get_model_info(
    model: str, repo: str = "onnx/models:main", opset: int | None = None
) -> ModelInfo: ...

def load(
    model: str,
    repo: str = "onnx/models:main",
    opset: int | None = None,
    force_reload: bool = False,
    silent: bool = False,
) -> onnx.ModelProto | None: ...

def download_model_with_test_data(
    model: str,
    repo: str = "onnx/models:main",
    opset: int | None = None,
    force_reload: bool = False,
    silent: bool = False,
) -> str | None: ...

def load_composite_model(
    network_model: str,
    preprocessing_model: str,
    network_repo: str = "onnx/models:main",
    preprocessing_repo: str = "onnx/models:main",
    opset: int | None = None,
    force_reload: bool = False,
    silent: bool = False,
) -> onnx.ModelProto | None: ...

Import

import onnx.hub
# or
from onnx import hub

I/O Contract

Inputs

Name	Type	Required	Description
model	str	Yes	The name of the ONNX model as it appears in the hub manifest (case-sensitive for get_model_info/load)
repo	str	No	Repository specification in format "user/repo[:branch]", defaults to "onnx/models:main"
opset	int or None	No	The opset version to select; None selects the largest available opset
force_reload	bool	No	Whether to force re-download even if the model is cached (default: False)
silent	bool	No	Whether to suppress security warnings for untrusted repos (default: False)
tags	list[str] or None	No	Tags to filter models by when listing (default: None returns all)
new_dir	str	Yes (for set_dir)	New cache directory path

Outputs

Name	Type	Description
model_proto	onnx.ModelProto or None	The loaded ONNX model protobuf, or None if the user declines an untrusted download
model_info	ModelInfo	Metadata about a model including name, path, SHA, tags, and opset
model_list	list[ModelInfo]	List of models matching the given filters
cache_dir	str	The current hub cache directory path
extracted_path	str or None	Path to extracted model directory (for download_model_with_test_data)

Usage Examples

import onnx.hub

# List all available models
all_models = onnx.hub.list_models()
for m in all_models:
    print(m.model, m.opset)

# List models with specific tags
vision_models = onnx.hub.list_models(tags=["vision"])

# Get info about a specific model
info = onnx.hub.get_model_info("MNIST")
print(info.model, info.opset, info.model_sha)

# Download and load a model
model = onnx.hub.load("MNIST")
print(model.graph.input[0].name)

# Load a specific opset version
model_v8 = onnx.hub.load("MNIST", opset=8)

# Force re-download from cache
model = onnx.hub.load("MNIST", force_reload=True)

# Change the cache directory
onnx.hub.set_dir("/my/custom/cache")
print(onnx.hub.get_dir())

# Download model with test data
test_dir = onnx.hub.download_model_with_test_data("MNIST")

# Build a composite model with preprocessing
composite = onnx.hub.load_composite_model(
    network_model="resnet50",
    preprocessing_model="resnet50_preprocessing"
)

Related Pages

• Environment:Onnx_Onnx_Python_Runtime_Environment