expo run

Build and run your app natively on iOS and Android devices.

The expo run commands compile your native code and launch your app on iOS simulators, Android emulators, or physical devices. These commands are essential for testing native modules and custom native code.

expo run:ios

Build and run the iOS app binary locally.

Usage

npx expo run:ios [options]

Options

--device · string | boolean

Device name or UDID to build the app on. Alias: -d

Can be:

• Device name (e.g., “iPhone 15 Pro”)
• Device UDID for physical devices
• Boolean flag to select from available devices

--scheme · string | boolean

Xcode scheme to build. If not specified, the first scheme in the workspace is used.

--configuration · string

Xcode configuration to use. Options: Debug or Release. Default: Debug

--no-build-cache · boolean

Clear the native derived data before building. Use this when you encounter build issues.

--no-install · boolean

Skip installing npm dependencies before building.

--no-bundler · boolean

Skip starting the Metro bundler. Use this if Metro is already running.

--port · number

Port to start the Metro bundler on. Default: 8081. Alias: -p

--binary · string

Path to existing .app or .ipa file to install instead of building.

Examples

Basic iOS Build

Build and run on default simulator:

npx expo run:ios

Specific Device

Run on a specific simulator:

npx expo run:ios --device "iPhone 15 Pro"

Run on physical device by UDID:

npx expo run:ios --device 00008030-001234567890ABCD

Production Build

Build with Release configuration (unsigned):

npx expo run:ios --configuration Release

This creates an optimized build without debug symbols, useful for testing production performance.

Clean Build

Clear derived data for a fresh build:

npx expo run:ios --no-build-cache

Custom Scheme

Build a specific scheme:

npx expo run:ios --scheme MyAppProd

Without Metro

If Metro is already running:

npx expo run:ios --no-bundler

Platform Requirements

• macOS only - iOS development is not supported on Windows or Linux
• Xcode - Install from the Mac App Store
• iOS Simulator - Included with Xcode
• CocoaPods - Installed automatically if not present

How It Works

1. Runs prebuild - Generates native iOS project if needed
2. Installs CocoaPods - Runs pod install in the ios directory
3. Resolves device - Selects or launches simulator
4. Builds with Xcode - Compiles native code using xcodebuild
5. Installs app - Deploys to simulator or device
6. Starts Metro - Launches bundler for JavaScript
7. Opens app - Launches the app on the device

expo run:android

Build and run the Android app binary locally.

Usage

npx expo run:android [options]

Options

--device · string | boolean

Device name to run the app on. Alias: -d

Can be:

• Device name or ID from adb devices
• Boolean flag to select from available devices

--variant · string

Build variant or product flavor and build variant. Default: debug

Examples:

• debug - Debug build
• release - Release build
• productionDebug - Product flavor with debug build type

--no-build-cache · boolean

Clear the native build cache before building.

--no-install · boolean

Skip installing npm dependencies before building.

--no-bundler · boolean

Skip starting the Metro bundler.

--port · number

Port to start the dev server on. Default: 8081. Alias: -p

--binary · string

Path to existing .apk or .aab file to install instead of building.

--app-id · string

Custom Android application ID to launch. Overrides the default package name.

Examples

Basic Android Build

Build and run on default device/emulator:

npx expo run:android

Specific Device

Run on a specific device:

npx expo run:android --device emulator-5554

List available devices:

adb devices

Production Build

Build with release variant:

npx expo run:android --variant release

Note: Release builds require signing configuration in android/app/build.gradle.

Clean Build

Clear build cache:

npx expo run:android --no-build-cache

Custom App ID

Launch a specific application ID:

npx expo run:android --app-id com.mycompany.myapp.debug

Install Existing APK

Install a pre-built APK:

npx expo run:android --binary ./app-release.apk

Platform Requirements

• Java Development Kit (JDK) - Version 17 or newer
• Android Studio or Android SDK
• Android emulator or physical device with USB debugging enabled

How It Works

1. Runs prebuild - Generates native Android project if needed
2. Resolves device - Selects device or launches emulator
3. Configures Gradle - Sets up build properties
4. Builds with Gradle - Compiles native code
5. Installs APK - Deploys to device via ADB
6. Starts Metro - Launches bundler for JavaScript
7. Opens app - Launches the app on the device

Common Use Cases

Development Workflow

Use expo run commands when you need to:

• Test native modules and APIs
• Debug platform-specific code
• Verify native build configuration
• Test on physical devices
• Profile app performance
• Test production builds locally

When Not to Use

For JavaScript-only changes, use expo start instead:

# Faster for JS development
npx expo start --ios
npx expo start --android

This skips the native build step and just installs/launches the app.

Device Selection

iOS Devices

List available iOS simulators:

xcrun simctl list devices

Boot a specific simulator:

xcrun simctl boot "iPhone 15 Pro"

Android Devices

List connected Android devices:

adb devices

Launch an emulator:

emulator -avd Pixel_7_API_34

Troubleshooting

iOS Build Failures

Clear derived data:

rm -rf ~/Library/Developer/Xcode/DerivedData
npx expo run:ios --no-build-cache

Update CocoaPods:

cd ios
pod install --repo-update
cd ..

Android Build Failures

Clean Gradle cache:

cd android
./gradlew clean
cd ..
npx expo run:android --no-build-cache

Invalid cache or corrupted Gradle:

cd android
./gradlew clean --no-daemon
rm -rf .gradle
cd ..

Code Signing (iOS)

For physical devices, you need a development certificate:

1. Open ios/*.xcworkspace in Xcode
2. Select your team in Signing & Capabilities
3. Connect your device
4. Trust the certificate on your device

ADB Connection Issues (Android)

Restart ADB server:

adb kill-server
adb start-server

Enable USB debugging on your Android device:

1. Go to Settings → About Phone
2. Tap Build Number 7 times
3. Go to Developer Options
4. Enable USB Debugging

Comparing with expo start

Feature	expo start	expo run
Native builds	Uses existing binary	Compiles native code
Speed	Fast	Slower (compile time)
Use case	JS development	Native development
Requirements	Expo Go or dev build	Xcode/Android Studio
Native changes	Not reflected	Reflected

Use expo run when working with native code, expo start for everything else.