1<!---- DO NOT MODIFY Progress Bar Start ---> 2<div class="progress-bar-wrapper"> 3 <div class="progress-bar-item"> 4 <div class="step-number" id="step-1">1</div> 5 <span class="step-caption" id="caption-1"></span> 6 </div> 7 <div class="progress-bar-item"> 8 <div class="step-number" id="step-2">2</div> 9 <span class="step-caption" id="caption-2"></span> 10 </div> 11 <div class="progress-bar-item"> 12 <div class="step-number" id="step-3">3</div> 13 <span class="step-caption" id="caption-3"></span> 14 </div> 15 <div class="progress-bar-item"> 16 <div class="step-number" id="step-4">4</div> 17 <span class="step-caption" id="caption-4"></span> 18 </div> 19</div> 20<!---- DO NOT MODIFY Progress Bar End---> 21 22# Setting Up ExecuTorch 23In this section, we'll learn how to 24* Set up an environment to work on ExecuTorch 25* Generate a sample ExecuTorch program 26* Build and run a program with the ExecuTorch runtime 27 28## System Requirements 29### Operating System 30 31We've tested these instructions on the following systems, although they should 32also work in similar environments. 33 34 35Linux (x86_64) 36- CentOS 8+ 37- Ubuntu 20.04.6 LTS+ 38- RHEL 8+ 39 40macOS (x86_64/M1/M2) 41- Big Sur (11.0)+ 42 43Windows (x86_64) 44- Windows Subsystem for Linux (WSL) with any of the Linux options 45 46### Software 47* `conda` or another virtual environment manager 48 - We recommend `conda` as it provides cross-language 49 support and integrates smoothly with `pip` (Python's built-in package manager) 50 - Otherwise, Python's built-in virtual environment manager `python venv` is a good alternative. 51* `g++` version 7 or higher, `clang++` version 5 or higher, or another 52 C++17-compatible toolchain. 53 54Note that the cross-compilable core runtime code supports a wider range of 55toolchains, down to C++17. See the [Runtime Overview](./runtime-overview.md) for 56portability details. 57 58## Quick Setup: Colab/Jupyter Notebook Prototype 59 60To utilize ExecuTorch to its fullest extent, please follow the setup instructions provided below to install from source. 61 62Alternatively, if you would like to experiment with ExecuTorch quickly and easily, we recommend using the following [colab notebook](https://colab.research.google.com/drive/1qpxrXC3YdJQzly3mRg-4ayYiOjC6rue3?usp=sharing) for prototyping purposes. You can install directly via `pip` for basic functionality. 63 ```bash 64 pip install executorch 65 ``` 66 67 68## Environment Setup 69 70### Create a Virtual Environment 71 72[Install conda on your machine](https://conda.io/projects/conda/en/latest/user-guide/install/index.html). Then, create a virtual environment to manage our dependencies. 73 ```bash 74 # Create and activate a conda environment named "executorch" 75 conda create -yn executorch python=3.10.0 76 conda activate executorch 77 ``` 78 79### Clone and install ExecuTorch requirements 80 81 ```bash 82 # Clone the ExecuTorch repo from GitHub 83 # 'main' branch is the primary development branch where you see the latest changes. 84 # 'viable/strict' contains all of the commits on main that pass all of the necessary CI checks. 85 git clone --branch viable/strict https://github.com/pytorch/executorch.git 86 cd executorch 87 88 # Update and pull submodules 89 git submodule sync 90 git submodule update --init 91 92 # Install ExecuTorch pip package and its dependencies, as well as 93 # development tools like CMake. 94 # If developing on a Mac, make sure to install the Xcode Command Line Tools first. 95 ./install_requirements.sh 96 ``` 97 98 Use the [`--pybind` flag](https://github.com/pytorch/executorch/blob/main/install_requirements.sh#L26-L29) to install with pybindings and dependencies for other backends. 99 ```bash 100 ./install_requirements.sh --pybind <coreml | mps | xnnpack> 101 ``` 102After setting up your environment, you are ready to convert your PyTorch programs 103to ExecuTorch. 104 105> **_NOTE:_** Cleaning the build system 106> 107> When fetching a new version of the upstream repo (via `git fetch` or `git 108> pull`) it is a good idea to clean the old build artifacts. The build system 109> does not currently adapt well to changes in build dependencies. 110> 111> You should also update and pull the submodules again, in case their versions 112> have changed. 113> 114> ```bash 115> # From the root of the executorch repo: 116> rm -rf cmake-out pip-out 117> git submodule sync 118> git submodule update --init 119> ``` 120 121## Create an ExecuTorch program 122 123After setting up your environment, you are ready to convert your PyTorch programs 124to ExecuTorch. 125 126### Export a Program 127ExecuTorch provides APIs to compile a PyTorch [`nn.Module`](https://pytorch.org/docs/stable/generated/torch.nn.Module.html) to a `.pte` binary consumed by the ExecuTorch runtime. 1281. [`torch.export`](https://pytorch.org/docs/stable/export.html) 1291. [`exir.to_edge`](https://pytorch.org/executorch/stable/export-to-executorch-api-reference.html#exir.to_edge) 1301. [`exir.to_executorch`](ir-exir.md) 1311. Save the result as a [`.pte` binary](pte-file-format.md) to be consumed by the ExecuTorch runtime. 132 133 134Let's try this using with a simple PyTorch model that adds its inputs. 135 136Create `export_add.py` in a new directory outside of the ExecuTorch repo. 137 138**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.** 139 140``` 141mkdir -p ../example_files 142cd ../example_files 143touch export_add.py 144``` 145 146Add the following code to `export_add.py`: 147```python 148import torch 149from torch.export import export 150from executorch.exir import to_edge 151 152# Start with a PyTorch model that adds two input tensors (matrices) 153class Add(torch.nn.Module): 154 def __init__(self): 155 super(Add, self).__init__() 156 157 def forward(self, x: torch.Tensor, y: torch.Tensor): 158 return x + y 159 160# 1. torch.export: Defines the program with the ATen operator set. 161aten_dialect = export(Add(), (torch.ones(1), torch.ones(1))) 162 163# 2. to_edge: Make optimizations for Edge devices 164edge_program = to_edge(aten_dialect) 165 166# 3. to_executorch: Convert the graph to an ExecuTorch program 167executorch_program = edge_program.to_executorch() 168 169# 4. Save the compiled .pte program 170with open("add.pte", "wb") as file: 171 file.write(executorch_program.buffer) 172 173``` 174 175Then, execute it from your terminal. 176```bash 177python3 export_add.py 178``` 179 180If it worked you'll see `add.pte` in that directory 181 182See the [ExecuTorch export tutorial](tutorials_source/export-to-executorch-tutorial.py) to learn more about the export process. 183 184 185## Build & Run 186 187After creating a program go back to the executorch directory to execute it using the ExecuTorch runtime. 188``` 189cd ../executorch 190``` 191 192For now, let's use [`executor_runner`](https://github.com/pytorch/executorch/blob/main/examples/portable/executor_runner/executor_runner.cpp), an example that runs the `forward` method on your program using the ExecuTorch runtime. 193 194### Build Tooling Setup 195The 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. 196 ```bash 197 # Clean and configure the CMake build system. Compiled programs will 198 # appear in the executorch/cmake-out directory we create here. 199 (rm -rf cmake-out && mkdir cmake-out && cd cmake-out && cmake ..) 200 201 # Build the executor_runner target 202 cmake --build cmake-out --target executor_runner -j9 203 ``` 204 205> **_NOTE:_** Cleaning the build system 206> 207> When fetching a new version of the upstream repo (via `git fetch` or `git 208> pull`) it is a good idea to clean the old build artifacts. The build system 209> does not currently adapt well to changes in build dependencies. 210> 211> You should also update and pull the submodules again, in case their versions 212> have changed. 213> 214> ```bash 215> # From the root of the executorch repo: 216> rm -rf cmake-out pip-out 217> git submodule sync 218> git submodule update --init 219> ``` 220 221### Run Your Program 222 223Now that we've exported a program and built the runtime, let's execute it! 224 225 ```bash 226 ./cmake-out/executor_runner --model_path ../example_files/add.pte 227 ``` 228Our output is a `torch.Tensor` with a size of 1. The `executor_runner` sets all input values to a [`torch.ones`](https://pytorch.org/docs/stable/generated/torch.ones.html) tensor, so when `x=[1]` and `y=[1]`, we get `[1]+[1]=[2]` 229 :::{dropdown} Sample Output 230 231 ``` 232Output 0: tensor(sizes=[1], [2.]) 233 ``` 234 ::: 235 236To learn how to build a similar program, visit the [Runtime APIs Tutorial](extension-module.md). 237 238## Next Steps 239 240Congratulations! You have successfully exported, built, and run your first 241ExecuTorch program. Now that you have a basic understanding of ExecuTorch, 242explore its advanced features and capabilities below. 243 244* Build an [Android](demo-apps-android.md) or [iOS](demo-apps-ios.md) demo app 245* Learn more about the [export process](export-overview.md) 246* Dive deeper into the [Export Intermediate Representation (EXIR)](ir-exir.md) for complex export workflows 247* Refer to [advanced examples in executorch/examples](https://github.com/pytorch/executorch/tree/main/examples) 248