Runtime Python API Reference

The Python executorch.runtime module wraps the C++ ExecuTorch runtime. It can load and execute serialized .pte program files: see the Export to ExecuTorch Tutorial for how to convert a PyTorch nn.Module to an ExecuTorch .pte program file. Execution accepts and returns torch.Tensor values, making it a quick way to validate the correctness of the program.

For detailed information on how APIs evolve and the deprecation process, please refer to the ExecuTorch API Life Cycle and Deprecation Policy.

Example usage:

from pathlib import Path

import torch
from executorch.runtime import Runtime, Program, Method

et_runtime: Runtime = Runtime.get()
program: Program = et_runtime.load_program(Path("/tmp/program.pte"))
print("Program methods:", program.method_names)
forward: Method = program.load_method("forward")

inputs = (torch.ones(2, 2), torch.ones(2, 2))
outputs = forward.execute(inputs)
print(f"Ran forward({inputs})")
print(f"  outputs: {outputs}")

Example output:

Program methods: {'forward'}
Ran forward((tensor([[1., 1.],
        [1., 1.]]), tensor([[1., 1.],
        [1., 1.]])))
  outputs: [tensor([[2., 2.],
        [2., 2.]])]

Example usage with ETDump generation:

Note: ETDump requires building ExecuTorch with event tracing enabled (CMake option EXECUTORCH_ENABLE_EVENT_TRACER=ON).

from pathlib import Path
import os

import torch
from executorch.runtime import Runtime, Program, Method

# Create program with etdump generation enabled
et_runtime: Runtime = Runtime.get()
program: Program = et_runtime.load_program(
    Path("/tmp/program.pte"),
    enable_etdump=True,
    debug_buffer_size=int(1e7),  # 10MB buffer to capture all debug info
)

# Load method and execute
forward: Method = program.load_method("forward")
inputs = (torch.ones(2, 2), torch.ones(2, 2))
outputs = forward.execute(inputs)

# Write etdump result to file
etdump_file = "/tmp/etdump_output.etdp"
debug_file = "/tmp/debug_output.bin"
program.write_etdump_result_to_file(etdump_file, debug_file)

# Check that files were created
print(f"ETDump file created: {os.path.exists(etdump_file)}")
print(f"Debug file created: {os.path.exists(debug_file)}")
print("Directory contents:", os.listdir("/tmp"))

Example output:

ETDump file created: True
Debug file created: True
Directory contents: ['program.pte', 'etdump_output.etdp', 'debug_output.bin']

Example usage with backend and operator introspection:

from executorch.runtime import Runtime

runtime = Runtime.get()

# Check available backends
backends = runtime.backend_registry.registered_backend_names
print(f"Available backends: {backends}")

# Check if a specific backend is available
if runtime.backend_registry.is_available("XnnpackBackend"):
    print("XNNPACK backend is available")

# List all registered operators
operators = runtime.operator_registry.operator_names
print(f"Number of registered operators: {len(operators)}")

Example output:

Available backends: ['XnnpackBackend', ...]  # Depends on your build configuration
XNNPACK backend is available
Number of registered operators: 247  # Depends on linked kernels

class executorch.runtime.Runtime(*, legacy_module)

An instance of the ExecuTorch runtime environment.

This can be used to concurrently load and execute any number of ExecuTorch programs and methods.

backend_registry

Registry for querying available hardware backends.

operator_registry

Registry for querying available operators/kernels.

static get()

Gets the Runtime singleton.

load_program(data, *, verification=<Verification.InternalConsistency: 1>, enable_etdump=False, debug_buffer_size=0)

Loads an ExecuTorch program from a PTE binary.

Parameters:

• data – The binary program data to load. Can be a file path (str or Path), bytes/bytearray, or a file-like object.

• verification – Level of program verification to perform (Minimal or InternalConsistency). Default is InternalConsistency.

• enable_etdump – If True, enables ETDump profiling for runtime performance analysis. Default is False.

• debug_buffer_size – Size of the debug buffer in bytes for ETDump data. Only used when enable_etdump=True. Default is 0.

Returns:

The loaded Program instance.

class executorch.runtime.OperatorRegistry(legacy_module)

The registry of operators that are available to the runtime.

property operator_names

Returns the names of all registered operators as a set of strings.

class executorch.runtime.Program(program, data)

An ExecuTorch program, loaded from binary PTE data.

This can be used to load the methods/models defined by the program.

load_method(name)

Loads a method from the program.

Parameters:

name – The name of the method to load.

Returns:

The loaded method.

property method_names

Returns method names of the Program as a set of strings.

class executorch.runtime.Method(method)

An ExecuTorch method, loaded from a Program. This can be used to execute the method with inputs.

execute(inputs)

Executes the method with the given inputs.

Parameters:

inputs – A sequence of input values, typically torch.Tensor objects.

Returns:

A list of output values, typically torch.Tensor objects.

property metadata

Gets the metadata for the method.

The metadata includes information about input and output specifications, such as tensor shapes, data types, and memory requirements.

Returns:

The MethodMeta object containing method specifications.