building

Building ExecuTorch

Step 1: Ensure Python environment (detect and fix automatically)

Path A — conda (preferred):

# Initialize conda for non-interactive shells (required in Claude Code / CI)
eval "$(conda shell.bash hook 2>/dev/null)"

# Check if executorch conda env exists; create if not
conda env list 2>/dev/null | grep executorch || \
  ls "$(conda info --base 2>/dev/null)/envs/" 2>/dev/null | grep executorch || \
  conda create -yn executorch python=3.12

# Activate
conda activate executorch

Path B — no conda (fall back to venv):

# Find a compatible Python (3.10–3.14).
python3.12 -m venv .executorch-venv   # or python3.11, python3.10, python3.13, python3.14
source .executorch-venv/bin/activate
pip install --upgrade pip

Then verify (either path):

Run python --version and cmake --version. Fix automatically:

• Python not 3.10–3.14: recreate the env with a correct Python version.
• cmake missing or < 3.24: run pip install 'cmake>=3.24' inside the env.
• cmake >= 4.0: works in practice, no action needed.

Parallel jobs: $(sysctl -n hw.ncpu) on macOS, $(nproc) on Linux.

Step 2: Build

Route based on what the user asks for:

• User mentions Android → skip to Cross-compilation: Android
• User mentions iOS or frameworks → skip to Cross-compilation: iOS
• User mentions a model name (llama, whisper, etc.) → skip to LLM / ASR model runner
• User mentions C++ runtime or cmake → skip to C++ runtime
• Otherwise → default to Python package below

Python package (default)

conda activate executorch
./install_executorch.sh --editable    # editable install from source

This handles everything: submodules, deps, C++ build, Python install. Takes ~10 min on Apple Silicon.

For subsequent rebuilds (deps already present): pip install -e . --no-build-isolation

For minimal install (skip example deps): ./install_executorch.sh --minimal

Enable additional backends:

CMAKE_ARGS="-DEXECUTORCH_BUILD_COREML=ON -DEXECUTORCH_BUILD_MPS=ON" ./install_executorch.sh --editable

Verify: python -c "from executorch.exir import to_edge_transform_and_lower; print('OK')"

LLM / ASR model runner (simplest path for running models)

conda activate executorch
make <model>-<backend>

Available targets (run make help for full list):

Output: cmake-out/examples/models/<model>/<runner>

C++ runtime (standalone)

With presets (recommended):

Then: cmake --build cmake-out --config Release -j$(sysctl -n hw.ncpu) (macOS) or cmake --build cmake-out -j$(nproc) (Linux)

LLM libraries via workflow presets (configure + build + install in one command):

cmake --workflow --preset llm-release        # CPU
cmake --workflow --preset llm-release-metal  # Metal (macOS)
cmake --workflow --preset llm-release-cuda   # CUDA (Linux/Windows)

Manual CMake (custom flags):

cmake -B cmake-out \
  -DCMAKE_BUILD_TYPE=Release \
  -DEXECUTORCH_BUILD_XNNPACK=ON \
  -DEXECUTORCH_BUILD_KERNELS_OPTIMIZED=ON \
  -DEXECUTORCH_BUILD_EXTENSION_MODULE=ON \
  -DEXECUTORCH_BUILD_EXTENSION_FLAT_TENSOR=ON \
  -DEXECUTORCH_BUILD_EXTENSION_NAMED_DATA_MAP=ON \
  -DEXECUTORCH_BUILD_EXTENSION_DATA_LOADER=ON \
  -DEXECUTORCH_BUILD_EXTENSION_TENSOR=ON
cmake --build cmake-out --parallel "$(nproc 2>/dev/null || sysctl -n hw.ncpu)"

Run cmake --list-presets to see all available presets.

Cross-compilation

iOS/macOS frameworks:

./scripts/build_apple_frameworks.sh --coreml --mps --xnnpack

Link in Xcode with -all_load linker flag.

Android:

Requires ANDROID_NDK on PATH (typically set by Android Studio or standalone NDK install).

# Verify NDK is available
echo $ANDROID_NDK           # must point to NDK root, e.g. ~/Library/Android/sdk/ndk/<version>
export ANDROID_ABIS=arm64-v8a BUILD_AAR_DIR=aar-out
mkdir -p $BUILD_AAR_DIR && sh scripts/build_android_library.sh

Key build options

Most commonly needed flags (full list: CMakeLists.txt):

Troubleshooting

Build output

From ./install_executorch.sh (Python package):

From CMake builds (cmake --install with CMAKE_INSTALL_PREFIX=cmake-out):

From cross-compilation:

Tips

• Always use Release for benchmarking; Debug is 5–10x slower
• ccache is auto-detected if installed (brew install ccache)
• Ninja is faster than Make (-G Ninja) — but --preset macos uses Xcode generator
• For LLM workflows, make <model>-<backend> is the simplest path
• After git pull, clean and re-init submodules before rebuilding