matlab-import-external-ai-model

Import Deep Learning Models into MATLAB

Import trained PyTorch, ONNX, or Keras 3 models into MATLAB as dlnetwork objects and verify numerical correctness.

When to Use

User wants to import a deep learning model from PyTorch, ONNX, or Keras/TensorFlow
User has .pt2, .pt, .onnx, or .keras files to bring into MATLAB
User mentions importNetworkFromPyTorch, importNetworkFromONNX, importNetworkFromKeras, or importNetworkFromTensorFlow
User mentions torch.export.export, torch.jit.trace, PyTorchInputSizes, InputDataFormats, or matlabsaver
User encounters import errors, unsupported operator warnings, uninitialized networks, or 0 learnables after import
User wants to validate that an imported model matches the source framework's outputs

When NOT to Use

Exporting MATLAB networks to ONNX/PyTorch (use exportONNXNetwork / exportNetworkToPyTorch)
Training or fine-tuning after import — use /matlab-train-network
Deploying to embedded hardware — use /matlab-deploy-embedded-ai
Simulink integration after import (agent handles this well without guidance)

Router: Which Framework?

Q: What format is the source model?
 |
 +-- .pt2 (PyTorch exported program) ──────────> PYTORCH IMPORT below
 +-- .pt (PyTorch traced model) ───────────────> PYTORCH IMPORT below
 +-- .onnx ────────────────────────────────────> ONNX IMPORT below
 +-- .keras / TensorFlow 2.16+ / matlabsaver ──> KERAS IMPORT below
 +-- Unknown ("import my model") ──────────────> Ask: framework? file extension?

PyTorch Import

Full pipeline: export from PyTorch → import into MATLAB → validate numerics.

Determine Starting Point

User has	Action
PyTorch model (code or saved)	Export as .pt2 first → see `references/pytorch-export-guidance.md`
`.pt2` file (exported program)	Import directly (below)
`.pt` file (traced model)	Import with input sizes (below)

Always prefer .pt2 over .pt. If user has a traced model, recommend re-exporting with torch.export.export first. Only use traced path if re-export is not feasible.

Import .pt2 (Exported Program)

net = importNetworkFromPyTorch("model.pt2");

No input size argument needed — shape info is embedded in the .pt2 file.

Import .pt (Traced Model)

net = importNetworkFromPyTorch("model.pt", ...
    PyTorchInputSizes=[1 3 224 224]);

PyTorchInputSizes is mandatory for traced models. Specify sizes in PyTorch dimension ordering. For multiple inputs use a cell array: {[1 3 256 256], [1 10]}.

Name-Value Arguments

Argument	When to use
`PyTorchInputSizes`	Required for traced models (.pt). Not needed for .pt2
`Namespace`	Control where auto-generated custom layer files are stored
`PreferredNestingType`	Choose `"networklayer"` (default) or `"customlayer"`

PyTorch Critical Mistakes

Mistake	Correct Approach
Using `InputShape` NV argument	Does not exist — use `PyTorchInputSizes` for .pt, nothing for .pt2
Using `PackageName` NV argument	Deprecated — use `Namespace`
Not calling `model.to("cpu")` before export	Always `model.to("cpu")` before export
Not checking PyTorch version before export	Assert `torch.__version__` starts with "2.8"
Passing `PyTorchInputSizes` for .pt2	Unnecessary — .pt2 embeds shape info, omit it
Guessing input size for unknown models	Always ask the user for exact input dimensions
Assuming `net.InputNames` matches `forward()` order	Importer may reorder — always check `net.InputNames`

PyTorch Conventions

Always model.to("cpu") and model.eval() before export
Always verify PyTorch version is 2.8 before exporting as .pt2
Never guess input sizes — ask the user or inspect the model
Use Namespace not PackageName for custom layer storage
Prefer .pt2 over .pt — recommend torch.export.export over torch.jit.trace

PyTorch References

references/pytorch-export-guidance.md — Full Python-side export procedure
references/pytorch-import-guidance.md — Detailed MATLAB import for both formats
references/pytorch-numeric-validation.md — Dimension conversion and tolerance comparison
references/pytorch-placeholder-guidance.md — Implementing unsupported ops in custom layers
scripts/validateImportedNetwork.m — Helper function for numeric validation against .npy reference data

ONNX Import

Import ONNX models using importNetworkFromONNX, diagnose issues, verify numerics.

Workflow

1. IMPORT  → importNetworkFromONNX with appropriate NVPs
2. DIAGNOSE → Check initialization, custom layers, warnings
3. RESOLVE  → Fix issues (InputDataFormats, placeholder functions)
4. VERIFY   → Compare outputs against ONNX Runtime (if installed)

CRITICAL: Do NOT re-import after step 3. Re-importing regenerates +ops/ and overwrites all custom implementations.

Import

net = importNetworkFromONNX("model.onnx");

If you know the input format:

net = importNetworkFromONNX("model.onnx", InputDataFormats="BCSS");

Diagnose and Resolve

If net.Initialized is false, read the input shape and re-import with InputDataFormats:

net = importNetworkFromONNX("model.onnx");
if ~net.Initialized
    inputLayer = net.Layers(1);
    fprintf("NumDims: %d\n", inputLayer.NumDims);
end

InputDataFormats Reference

Characters: B (batch), C (channel), S (spatial), T (time), U (unspecified).

ONNX Input Shape	InputDataFormats
[N, C, H, W]	`"BCSS"`
[N, C]	`"BC"`
[N, T, C]	`"BTC"`
[N, C, T]	`"BCT"`

Verify Against ONNX Runtime

If onnxruntime is installed in the user's Python environment, compare outputs. If not installed, skip — do not ask the user to install it.

try
    ort = py.importlib.import_module("onnxruntime");
    ortAvailable = true;
catch
    ortAvailable = false;
end

See references/onnx-validation-workflow.md for the full comparison procedure.

ONNX Critical Mistakes

Mistake	Correct Approach
Use `importONNXNetwork` or `importONNXLayers`	Legacy — always use `importNetworkFromONNX`
Re-import after implementing placeholders	Import once, then modify. Never re-import.
Guess InputDataFormats randomly	Read input shape from uninitialized network first
Skip numeric verification when ORT is available	Compare against ONNX Runtime if installed

ONNX Conventions

Always use importNetworkFromONNX — never legacy APIs
Verify numerically against ONNX Runtime after import (if installed)
Never re-import after modifying network or implementing placeholders
Use dlarray with explicit format strings: dlarray(data, "SSCB")
Report max absolute difference and assert tolerance < 1e-4 for float32

ONNX Reference

references/onnx-validation-workflow.md — Full ORT comparison including multi-output models

Keras Import

Import Keras 3 / TensorFlow 2.16+ models with full layer structure and learnables.

Decision Tree

Q1: What MATLAB release is available?
 +-- R2026a or newer ──> PATH 1 (matlabsaver + importNetworkFromKeras)
 +-- R2025b or older ──> Q2
      Q2: Does the model use Keras 3-specific features? (keras.ops, multi-backend)
       +-- No (standard layers) ──> PATH 2 (tf_keras downgrade)
       +-- Yes ────────────────────> PATH 3 (ONNX export fallback)

Path 1: matlabsaver + importNetworkFromKeras (R2026a+)

Python:

import matlabsaver
matlabsaver.save_for_matlab(model, "exportedModelFolder")

Apply the config.json patch for Keras 3.10+ compatibility (see references/keras-matlabsaver-workflow.md).

MATLAB:

net = importNetworkFromKeras("exportedModelFolder");
assert(numel(net.Learnables.Value) > 0, "Import failed: 0 learnables")

Path 2: tf_keras Downgrade (Pre-R2026a, Standard Layers Only)

Python:

import os
os.environ["TF_USE_LEGACY_KERAS"] = "1"  # MUST be before importing TensorFlow
import tf_keras as keras
model.save("savedModelFolder")

MATLAB:

net = importNetworkFromTensorFlow("savedModelFolder");

Path 3: ONNX Export (Fallback)

Requires tf2onnx in the Python environment: pip install tf2onnx

Python:

model.export("exportedModel.onnx", format="onnx")

MATLAB:

net = importNetworkFromONNX("exportedModel.onnx");

Keras Critical Mistakes

Mistake	Correct Approach
`importNetworkFromKeras` fails with "Brace indexing..."	Keras 3.10+ changed config.json — apply the patch (see reference)
`model.export("folder")` then `importNetworkFromTensorFlow`	No keras_metadata.pb → 0 learnables. Use matlabsaver instead
`TF_USE_LEGACY_KERAS=1` set after `import tensorflow`	Must be set before any TF import
Using deprecated `importKerasNetwork`	Use `importNetworkFromKeras` (R2026a+) or Path 2/3

Keras Conventions

Always verify imported network has non-zero learnables
Always check MATLAB release before choosing import path
Prefer Path 1 > Path 2 > Path 3 (ordered by fidelity)
Report number of layers and learnables after import

Keras References

references/keras-matlabsaver-workflow.md — Full matlabsaver procedure for R2026a+
references/keras-tf-keras-downgrade.md — tf_keras setup for pre-R2026a

Key Functions

Function	Framework	Purpose
`importNetworkFromPyTorch`	PyTorch	Import .pt2 or .pt as dlnetwork
`importNetworkFromONNX`	ONNX	Import .onnx as dlnetwork
`importNetworkFromKeras`	Keras	Import Keras 3 folder as dlnetwork (R2026a+)
`importNetworkFromTensorFlow`	TF/Keras	Import TF SavedModel as dlnetwork
`torch.export.export`	PyTorch	Export model as .pt2 (Python)
`matlabsaver.save_for_matlab`	Keras	Export Keras 3 for MATLAB (Python)
`predict`	All	Run inference on imported dlnetwork
`dlarray`	All	Labeled multi-dimensional array for deep learning

About this skill

When to Use

When NOT to Use

Router: Which Framework?

PyTorch Import

Determine Starting Point

Import .pt2 (Exported Program)

Import .pt (Traced Model)

Name-Value Arguments

PyTorch Critical Mistakes

PyTorch Conventions

PyTorch References

ONNX Import

Workflow

Import

Diagnose and Resolve

InputDataFormats Reference

Verify Against ONNX Runtime

ONNX Critical Mistakes

ONNX Conventions

ONNX Reference

Keras Import

Decision Tree

Path 1: matlabsaver + importNetworkFromKeras (R2026a+)

Path 2: tf_keras Downgrade (Pre-R2026a, Standard Layers Only)

Path 3: ONNX Export (Fallback)

Keras Critical Mistakes

Keras Conventions

Keras References

Key Functions