# Getting Started

React Native ExecuTorch is an on-device AI inference library for React Native, powered by [ExecuTorch](https://executorch.ai) — Meta's on-device inference runtime and a project under the PyTorch Foundation. It lets you run machine learning models directly on the user's phone with zero network calls, full offline capability, and guaranteed privacy. No data ever leaves the device.

The library ships with a curated set of pre-exported models covering computer vision, language models, text-to-speech, transcription, and more — all available in our [HuggingFace collection](https://huggingface.co/software-mansion/collections) and ready to use out of the box. You can also bring your own models and plug them into existing pipelines or build entirely custom ones from scratch.

## What is ExecuTorch?[​](#what-is-executorch "Direct link to What is ExecuTorch?")

[ExecuTorch](https://executorch.ai) is a PyTorch Core project — Meta's on-device inference runtime for deploying PyTorch models on edge devices. It takes standard PyTorch models and compiles them into an optimized `.pte` format that runs natively on mobile phones, AR/VR headsets, embedded systems, and custom accelerators.

The runtime supports hardware-accelerated backends for every major platform: XNNPACK for CPU acceleration across all platforms, Core ML and MLX on Apple devices, Vulkan for Android GPU, and more. It's a core part of the PyTorch ecosystem, with full support for the standard PyTorch model export workflow.

ExecuTorch handles the hard parts: memory planning, operator dispatch, and hardware delegate selection — so you don't have to. To learn more about the underlying runtime, check out the [ExecuTorch documentation](https://docs.pytorch.org/executorch/stable/index.html).

## Installation[​](#installation "Direct link to Installation")

Install [`react-native-executorch`](https://www.npmjs.com/package/react-native-executorch) alongside its peer dependencies:

* npm
* yarn
* pnpm

```bash
npm install react-native-executorch react-native-worklets react-native-blob-util

```

```bash
yarn add react-native-executorch react-native-worklets react-native-blob-util

```

```bash
pnpm add react-native-executorch react-native-worklets react-native-blob-util

```

![](data:image/svg+xml,%3csvg%20width='21'%20height='20'%20viewBox='0%200%2021%2020'%20fill='none'%20xmlns='http://www.w3.org/2000/svg'%3e%3cpath%20d='M10.5%2014.99V15'%20stroke='%23001A72'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M10.5%205V12'%20stroke='%23001A72'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M10.5%2019C15.4706%2019%2019.5%2014.9706%2019.5%2010C19.5%205.02944%2015.4706%201%2010.5%201C5.52944%201%201.5%205.02944%201.5%2010C1.5%2014.9706%205.52944%2019%2010.5%2019Z'%20stroke='%23001A72'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3c/svg%3e)![](data:image/svg+xml,%3csvg%20width='20'%20height='20'%20viewBox='0%200%2020%2020'%20fill='none'%20xmlns='http://www.w3.org/2000/svg'%3e%3cpath%20d='M10%2014.99V15'%20stroke='%23F8F9FF'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M10%205V12'%20stroke='%23F8F9FF'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M10%2019C14.9706%2019%2019%2014.9706%2019%2010C19%205.02944%2014.9706%201%2010%201C5.02944%201%201%205.02944%201%2010C1%2014.9706%205.02944%2019%2010%2019Z'%20stroke='%23F8F9FF'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3c/svg%3e)Requirements

React Native ExecuTorch requires:

* **New Architecture** enabled
* **React Native 0.83+** or **Expo SDK 55+** with [Development Builds](https://docs.expo.dev/develop/development-builds/introduction/) (**Expo Go is not supported** due to custom C++ native libraries)
* **`react-native-worklets` 0.10 or newer** (`>=0.10.0 <0.14.0`)
* **iOS 17.0+** / **Android 13+** (`minSdkVersion` >= 26); a bare app's `Podfile` needs `platform :ios, '17.0'`
* **`tar` on `PATH`** — the install-time download extracts with it; macOS, Linux and Windows 10 1803+ all ship one. Windows and Linux hosts can build for Android; iOS builds need macOS.

For supported React Native versions, see the [Compatibility table](https://docs.swmansion.com/react-native-executorch/docs/other/compatibility.md). If an install or a build fails, see [Troubleshooting](https://docs.swmansion.com/react-native-executorch/docs/other/troubleshooting.md) — most of it comes down to the package manager skipping the postinstall hook, or to `use_frameworks!`.

![](data:image/svg+xml,%3csvg%20width='21'%20height='20'%20viewBox='0%200%2021%2020'%20fill='none'%20xmlns='http://www.w3.org/2000/svg'%3e%3cpath%20d='M10.5%2014.99V15'%20stroke='%23001A72'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M10.5%205V12'%20stroke='%23001A72'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M10.5%2019C15.4706%2019%2019.5%2014.9706%2019.5%2010C19.5%205.02944%2015.4706%201%2010.5%201C5.52944%201%201.5%205.02944%201.5%2010C1.5%2014.9706%205.52944%2019%2010.5%2019Z'%20stroke='%23001A72'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3c/svg%3e)![](data:image/svg+xml,%3csvg%20width='20'%20height='20'%20viewBox='0%200%2020%2020'%20fill='none'%20xmlns='http://www.w3.org/2000/svg'%3e%3cpath%20d='M10%2014.99V15'%20stroke='%23F8F9FF'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M10%205V12'%20stroke='%23F8F9FF'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M10%2019C14.9706%2019%2019%2014.9706%2019%2010C19%205.02944%2014.9706%201%2010%201C5.02944%201%201%205.02944%201%2010C1%2014.9706%205.02944%2019%2010%2019Z'%20stroke='%23F8F9FF'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3c/svg%3e)Expo SDK 55 and 56

Both bundle a `react-native-worklets` older than 0.10 — 0.7.4 on SDK 55, 0.8.3 on SDK 56 — and `npx expo install` will pick that one. Install the version this library needs instead:

```bash
npm install react-native-worklets@^0.10.0

```

Any other package in your app that uses worklets has to be moved to a release built against the same version; two of them asking for different worklets gives you two incompatible native runtimes. Our own example apps reconcile them this way. **Expo SDK 54 cannot be supported**: it is React Native 0.81, below what worklets 0.10 accepts.

### Babel[​](#babel "Direct link to Babel")

The library runs inference on worklet threads, so add the worklets Babel plugin to `babel.config.js`. It must be the **last** entry in `plugins`:

```js
module.exports = {
  presets: ['module:@react-native/babel-preset'], // or 'babel-preset-expo'
  plugins: [
    // ...your other plugins
    'react-native-worklets/plugin',
  ],
};

```

Restart Metro with `--reset-cache` after changing it.

### Telemetry[​](#telemetry "Direct link to Telemetry")

Downloading one of our pre-exported models sends an anonymous download event by default. To opt out, call `setTelemetryEnabled(false)` once at startup. See [Anonymous Telemetry](https://docs.swmansion.com/react-native-executorch/docs/fundamentals/downloading-models.md#anonymous-telemetry--download-counter).

### Selecting native libraries[​](#selecting-native-libraries "Direct link to Selecting native libraries")

The native binaries — the ExecuTorch hardware backends (XNNPACK, Core ML, MLX, Vulkan), and third-party binaries — are downloaded on demand at install time. By default, **everything is downloaded and enabled**, so no configuration is required to get started.

If you want a smaller app or faster installs, declare what you use in a `react-native-executorch` block in your `package.json`, e.g.:

```json
{
  "react-native-executorch": {
    "features": ["classification", "styleTransfer"]
  }
}

```

The available options are:

* **`features`** — high-level task names. Each one expands to the backends and native libs it needs.
* **`backends`** — hardware backends directly, e.g. `xnnpack`, `coreml`, `vulkan`.
* **`libs`** — extra native libraries, see [options](https://docs.swmansion.com/react-native-executorch/docs/core-and-advanced/native-libraries.md#options).

The three lists are merged, so you can pair a `features` set with extra `backends` / `libs` entries. Re-run your package manager's install after editing. See [Native Libraries](https://docs.swmansion.com/react-native-executorch/docs/core-and-advanced/native-libraries.md) for details.

## Choose Your Path[​](#choose-your-path "Direct link to Choose Your Path")

Most mobile ML libraries force you into one of two extremes: opaque native black boxes that implement a fixed set of pipelines with no room for customization, or raw low-level bindings that leave you to wire up everything from preprocessing to memory management yourself.

What if you need a bit of both? Ready-to-use pipelines for common tasks, but also the freedom to drop down and build something custom when the out-of-the-box solution doesn't quite fit. That's exactly how React Native ExecuTorch is designed. The library is built around a clean **two-layer architecture** where the higher-level layer is implemented entirely on top of the lower-level one — not as separate C++ code hidden behind abstractions. This means:

* **Pipelines are transparent.** Every task pipeline (computer vision, LLM chat, etc.) is written in a few hundred lines of TypeScript — often less. You can read the full input/output contracts, preprocessing, and postprocessing logic in one place — no native code required.

* **Custom models just work.** Plug your own `.pte` into any existing pipeline — computer vision, LLM, whatever. The schema DSL declares exactly what each pipeline expects (tensor shapes, data types, preprocessing), so there's no guessing. Everything is in one place, readable in TypeScript.

* **You can always drop down.** When built-in pipelines don't fit your use case, the lower-level API gives you direct access to ExecuTorch model execution, native tensor operations, high-performance math/vision operators, and worklet threading. You build custom orchestration pipelines entirely in TypeScript — no C++ required — with complete control over preprocessing, inference, postprocessing, and memory.

### High-Level Task Pipelines[​](#high-level-task-pipelines "Direct link to High-Level Task Pipelines")

Have a specific problem to solve — computer vision, LLM chat, speech transcription? Each task has a ready-made pipeline you can drop into your app. Hooks handle downloading, caching, and memory disposal automatically. Imperative APIs give you manual control. Both work with pre-exported models from our [HuggingFace collection](https://huggingface.co/software-mansion/collections) or your own `.pte` files — as long as they match the pipeline's schema.

[Explore High-Level Pipelines →](https://docs.swmansion.com/react-native-executorch/docs/category/extensions.md)

### Lower-Level Runtime & Custom Pipelines[​](#lower-level-runtime--custom-pipelines "Direct link to Lower-Level Runtime & Custom Pipelines")

Working with a custom model or chaining multiple models together into a custom workflow? The lower-level API gives you direct access to ExecuTorch model execution, native tensor operations, native operators for vision, math, NLP, and audio, plus worklet-based multi-threading. You write the entire pipeline in TypeScript using the exact same building blocks and primitives we use to build the library's built-in extensions — no native C++ required.

[Explore Lower-Level API →](https://docs.swmansion.com/react-native-executorch/docs/category/core--advanced.md)
