4

Setting Up ExecuTorch¶

In this section, we’ll learn how to

Set up an environment to work on ExecuTorch
Generate a sample ExecuTorch program
Build and run a program with the ExecuTorch runtime

System Requirements¶

Operating System¶

We’ve tested these instructions on the following systems, although they should also work in similar environments.

Linux (x86_64)

CentOS 8+
Ubuntu 20.04.6 LTS+
RHEL 8+

macOS (x86_64/M1/M2)

Big Sur (11.0)+

Windows (x86_64)

Windows Subsystem for Linux (WSL) with any of the Linux options

Software¶

conda or another virtual environment manager
- We recommend conda as it provides cross-language support and integrates smoothly with pip (Python’s built-in package manager)
- Otherwise, Python’s built-in virtual environment manager python venv is a good alternative.
g++ version 7 or higher, clang++ version 5 or higher, or another C++17-compatible toolchain.

Note that the cross-compilable core runtime code supports a wider range of toolchains, down to C++17. See the Runtime Overview for portability details.

Quick Setup: Colab/Jupyter Notebook Prototype¶

To utilize ExecuTorch to its fullest extent, please follow the setup instructions provided below to install from source.

Alternatively, if you would like to experiment with ExecuTorch quickly and easily, we recommend using the following colab notebook for prototyping purposes. You can install directly via pip for basic functionality.

pip install executorch

Environment Setup¶

Create a Virtual Environment¶

Install conda on your machine. Then, create a virtual environment to manage our dependencies.

# Create and activate a conda environment named "executorch"
conda create -yn executorch python=3.10.0
conda activate executorch

Clone and install ExecuTorch requirements¶

# Clone the ExecuTorch repo from GitHub
# 'main' branch is the primary development branch where you see the latest changes.
# 'viable/strict' contains all of the commits on main that pass all of the necessary CI checks.
git clone --branch viable/strict https://github.com/pytorch/executorch.git
cd executorch

# Update and pull submodules
git submodule sync
git submodule update --init

# Install ExecuTorch pip package and its dependencies, as well as
# development tools like CMake.
# If developing on a Mac, make sure to install the Xcode Command Line Tools first.
./install_requirements.sh

Use the --pybind flag to install with pybindings and dependencies for other backends.

./install_requirements.sh --pybind <coreml | mps | xnnpack>

After setting up your environment, you are ready to convert your PyTorch programs to ExecuTorch.

NOTE: Cleaning the build system

When fetching a new version of the upstream repo (via git fetch or git pull) it is a good idea to clean the old build artifacts. The build system does not currently adapt well to changes in build dependencies.

You should also update and pull the submodules again, in case their versions have changed.
# From the root of the executorch repo:
rm -rf cmake-out pip-out
git submodule sync
git submodule update --init

Create an ExecuTorch program¶

After setting up your environment, you are ready to convert your PyTorch programs to ExecuTorch.

Export a Program¶

ExecuTorch provides APIs to compile a PyTorch nn.Module to a .pte binary consumed by the ExecuTorch runtime.

torch.export
exir.to_edge
exir.to_executorch
Save the result as a .pte binary to be consumed by the ExecuTorch runtime.

Let’s try this using with a simple PyTorch model that adds its inputs.

Create export_add.py in a new directory outside of the ExecuTorch repo.

Note: It’s important that this file does does not live in the directory that’s a parent of the executorch directory. We need python to import from site-packages, not from the repo itself.

mkdir -p ../example_files
cd ../example_files
touch export_add.py

Add the following code to export_add.py:

import torch
from torch.export import export
from executorch.exir import to_edge

# Start with a PyTorch model that adds two input tensors (matrices)
class Add(torch.nn.Module):
  def __init__(self):
    super(Add, self).__init__()

  def forward(self, x: torch.Tensor, y: torch.Tensor):
      return x + y

# 1. torch.export: Defines the program with the ATen operator set.
aten_dialect = export(Add(), (torch.ones(1), torch.ones(1)))

# 2. to_edge: Make optimizations for Edge devices
edge_program = to_edge(aten_dialect)

# 3. to_executorch: Convert the graph to an ExecuTorch program
executorch_program = edge_program.to_executorch()

# 4. Save the compiled .pte program
with open("add.pte", "wb") as file:
    file.write(executorch_program.buffer)

Then, execute it from your terminal.

python3 export_add.py

If it worked you’ll see add.pte in that directory

See the ExecuTorch export tutorial to learn more about the export process.

Build & Run¶

After creating a program go back to the executorch directory to execute it using the ExecuTorch runtime.

cd ../executorch

For now, let’s use executor_runner, an example that runs the forward method on your program using the ExecuTorch runtime.

Build Tooling Setup¶

The ExecuTorch repo uses CMake to build its C++ code. Here, we’ll configure it to build the executor_runner tool to run it on our desktop OS.

# Clean and configure the CMake build system. Compiled programs will
# appear in the executorch/cmake-out directory we create here.
(rm -rf cmake-out && mkdir cmake-out && cd cmake-out && cmake ..)

# Build the executor_runner target
cmake --build cmake-out --target executor_runner -j9

NOTE: Cleaning the build system

When fetching a new version of the upstream repo (via git fetch or git pull) it is a good idea to clean the old build artifacts. The build system does not currently adapt well to changes in build dependencies.

You should also update and pull the submodules again, in case their versions have changed.
# From the root of the executorch repo:
rm -rf cmake-out pip-out
git submodule sync
git submodule update --init

Run Your Program¶

Now that we’ve exported a program and built the runtime, let’s execute it!

./cmake-out/executor_runner --model_path ../example_files/add.pte

Our output is a torch.Tensor with a size of 1. The executor_runner sets all input values to a torch.ones tensor, so when x=[1] and y=[1], we get [1]+[1]=[2]

To learn how to build a similar program, visit the Runtime APIs Tutorial.

Next Steps¶

Congratulations! You have successfully exported, built, and run your first ExecuTorch program. Now that you have a basic understanding of ExecuTorch, explore its advanced features and capabilities below.

Build an Android or iOS demo app
Learn more about the export process
Dive deeper into the Export Intermediate Representation (EXIR) for complex export workflows
Refer to advanced examples in executorch/examples