ExecuTorch

Common errors

• ModuleNotFoundError: No module named 'executorch.backends.xnnpack'

  cause The specific backend delegate (e.g., XNNPACK) was not installed or built as part of your ExecuTorch installation.
  fix Install ExecuTorch with the required backend extra: `pip install executorch[xnnpack]` (replace `xnnpack` with the desired backend like `coreml`, `qualcomm`, etc.).

• RuntimeError: Input type mismatch. Expected (Tensor(shape=[1, 10], dtype=torch.float32)) got (Tensor(shape=[1, 5], dtype=torch.float32))

  cause The `example_inputs` provided to `torch.export` do not match the expected input types, shapes, or number of arguments for the model's `forward` method.
  fix Carefully review your model's `forward` signature and ensure `example_inputs` exactly mimic the data your model expects (e.g., `torch.randn(1, 10)` for a model expecting `(1, 10)` inputs).

• AttributeError: 'ExportedProgram' object has no attribute 'buffer'

  cause You are trying to access `.buffer` directly on the `ExportedProgram` returned by `torch.export`. The `.pte` binary data is contained in the object returned by `to_executorch`.
  fix First, pass the `ExportedProgram` to `to_executorch` to get the ExecuTorch program, then access `.buffer` on that object: `executorch_program = to_executorch(exported_program, ...); executorch_program.buffer`.

• TypeError: 'XnnpackPartitioner' object is not callable

  cause The `to_executorch` function expects a list of *instantiated* delegate objects or callables that return delegates, not the class type itself without parentheses.
  fix When passing the partitioner to `to_executorch`, instantiate it: `to_executorch(exported_program, [XnnpackPartitioner()])`.

Warnings

• breaking The `export_llm` API was significantly changed/unified in v0.7.0. Older custom LLM export scripts will likely break. The general model export workflow also transitioned from older `executorch.exporters.model_exporter.model_exporter.export_to_edge` to `torch.export` followed by `torch._export.executorch.to_executorch`.
  Fix: Migrate to the new unified `export_llm` API for LLMs or the `torch.export` + `to_executorch` pattern for general models, referencing the latest documentation.
• gotcha ExecuTorch involves two main components: the Python model preparation/exporter and the C++/native runtime for target devices. While `pip install executorch` handles the Python part, building the C++ runtime and SDK for specific embedded/mobile targets is a separate, often complex, and platform-specific process, requiring CMake and toolchain setup.
  Fix: Refer to the official ExecuTorch documentation for your specific target platform (Android, iOS, Cortex-M, etc.) for detailed build instructions for the native runtime.
• gotcha The `to_executorch` function requires a list of delegate builders (e.g., `[XnnpackPartitioner()]`) for model partitioning and optimization. If a backend delegate is not provided or not correctly configured/installed, the export process may fail or result in a program that does not utilize the target hardware effectively.
  Fix: Ensure you have installed ExecuTorch with the correct backend extras (e.g., `pip install executorch[xnnpack]`) and provide instantiated delegate builders to `to_executorch`, e.g., `to_executorch(exported_program, [YourDelegate()])`.
• gotcha ExecuTorch explicitly supports Python versions `>=3.10` and `<3.14`. Using unsupported Python versions may lead to installation issues, build failures, or runtime errors due to underlying dependencies like PyTorch itself.
  Fix: Ensure your Python environment is within the supported range (e.g., `python 3.10`, `3.11`, `3.12`). Use `pyenv` or `conda` to manage Python versions if needed.

Install

• pip install executorch Base installation
• pip install executorch[xnnpack] # Or [coreml], [qnn], etc. Installation with specific backend delegates

Imports

• to_executorch
  wrong:

  from executorch.exporters.model_exporter.model_exporter import export_to_edge

  correct:

  from torch._export.executorch import to_executorch

  The `export_to_edge` function was part of an older API and is replaced by `torch.export` combined with `to_executorch`.
• export

  from torch.export import export

  This is the standard PyTorch 2.0+ API for symbolic tracing, a prerequisite for ExecuTorch compilation.
• XnnpackPartitioner

  from executorch.backends.xnnpack.partition.xnnpack_partitioner import XnnpackPartitioner

  Example import for a common backend delegate. Other backends will have similar paths (e.g., `qualcomm`, `coreml`).

Quickstart

This quickstart demonstrates how to define a simple PyTorch model, export it using `torch.export`, and then convert it into an ExecuTorch program (.pte file) using the `to_executorch` function with an XNNPACK delegate. The resulting .pte file can then be deployed to target devices.

import torch
import torch.nn as nn
from torch._export.executorch import to_executorch
from torch.export import export
from executorch.backends.xnnpack.partition.xnnpack_partitioner import XnnpackPartitioner

# 1. Define a simple PyTorch model
class SimpleModel(nn.Module):
    def __init__(self):
        super().__init__()
        self.linear = nn.Linear(10, 2)

    def forward(self, x):
        return self.linear(x)

model = SimpleModel()

# 2. Define example inputs (crucial for tracing and export)
example_inputs = (torch.randn(1, 10),)

# 3. Export the model to an ExportedProgram using PyTorch's export API
exported_program = export(model, example_inputs)

# 4. Convert the ExportedProgram to an ExecuTorch program (.pte file)
# This requires specifying a backend delegate. XNNPACK is a common choice.
# Ensure `executorch[xnnpack]` or equivalent is installed.
executorch_program = to_executorch(exported_program, [XnnpackPartitioner()])

# 5. Save the ExecuTorch program to a file
with open("model.pte", "wb") as f:
    f.write(executorch_program.buffer)

print("Model successfully exported to model.pte")