How does a PyTorch nn.Module become an ExecuTorch .pte file?

## Why there is a pipeline at all Eager PyTorch is Python: `forward()` runs Python bytecode, dispatches through the ATen operator library, and allocates as it goes. A phone app has no Python interpreter and a hard binary-size budget, so on-device PyTorch splits the work in two. Everything dynamic and expensive happens **ahead of time** on your laptop or CI machine and produces one self-contained artifact; on the device, a small C++ runtime just walks that artifact. ExecuTorch is that runtime, and `.pte` (PyTorch ExecuTorch program) is that artifact. ## Stage 1 — capture: `torch.export.export` ``` ep = torch.export.export(model.eval(), (example_input,)) ``` This produces an `ExportedProgram`. Three things are worth knowing about it: - It is a **full-graph** capture. Unlike `torch.compile`, which is allowed to "graph break" and fall back to Python for anything it cannot trace, export must capture the entire model or fail loudly. There is no Python left to fall back to on device. - Parameters and buffers are **lifted** out of the module and become explicit graph inputs, recorded in a graph signature. The graph is a pure function; the weights travel alongside it. - It is traced with your **example inputs**, so concrete shapes and dtypes are baked in as guards unless you explicitly declare dimensions dynamic. Call `model.eval()` first. Exporting in training mode captures dropout and the batch-norm training branch, and the exported model then produces different numbers on device than it did in your validation loop — a silent-wrong-answer bug, not a crash. ## Stage 2 — lower: `to_edge_transform_and_lower` ``` edge = to_edge_transform_and_lower(ep, partitioner=[XnnpackPartitioner()]) ``` This does two jobs at once. It converts the ATen graph to the **Edge dialect** — the same operators, but constrained to what an edge runtime can serialize and execute (explicit dtypes, no Python objects, no training-only constructs) — and it runs the **partitioner**, which tags the subgraphs the chosen backend can accept. Each claimed subgraph is compiled by that backend into an opaque blob and replaced in the graph by a call-delegate node. Whatever the backend does not claim stays as ordinary Edge operators. The result is an `EdgeProgramManager`, a container around one or more exported methods. ## Stage 3 — emit: `to_executorch` ``` prog = edge.to_executorch() with open("model.pte", "wb") as f: f.write(prog.buffer) ``` `to_executorch()` runs **memory planning**: because the graph is static, the toolchain can compute up front how large the intermediate-tensor arena must be and where each intermediate lives inside it, so the runtime does almost no dynamic allocation. It returns an `ExecutorchProgramManager`; `.buffer` is the serialized program bytes. A `.pte` therefore contains far more than weights — the instruction stream, the constant tensors, any delegate blobs, the memory plan, and the signature of each exported method. ## The deprecated two-step Older tutorials show `to_edge(ep)` followed by `edge.to_backend(XnnpackPartitioner())`. That path still runs, but ExecuTorch prints a deprecation warning naming the `to_edge() + to_backend()` workflow and pointing at `to_edge_transform_and_lower`. The one-step call interleaves the edge transformation passes with partitioning so the backend sees a graph in the shape it expects; the split version could hand the partitioner a graph that had already been rewritten in ways it did not recognise. If you inherit code using the two-step form, migrating is usually a one-line change. ## Verifying before you ship You do not need a phone to smoke-test the artifact. The Python runtime bindings load the same `.pte`: ``` from executorch.runtime import Runtime method = Runtime.get().load_program("model.pte").load_method("forward") out = method.execute([example_input]) ``` Compare that output against the eager model's on the same input, with a tolerance — numerical drift from a delegate is normal, a completely different answer means you exported the wrong thing (training mode, a frozen branch, wrong preprocessing). ## Where it commonly goes wrong Export is the stage that fails, and it fails for a small set of reasons: data-dependent Python control flow that cannot be captured, shapes that got specialized to your example input, and operators with no Edge-dialect or backend implementation. None of these are runtime problems — they surface on your build machine, which is the whole point of doing the work ahead of time.