Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/expo/expo/llms.txt

Use this file to discover all available pages before exploring further.

Once you’ve created a development build, you need to install it on your test devices. Installation methods vary by platform and distribution strategy.

​
iOS Installation

​
iOS Simulator

Simulator builds are the easiest to install for local development.
1

Build for simulator

# Local build
npx expo run:ios --simulator

# Or EAS Build
eas build --profile development --platform ios
In eas.json, ensure simulator is enabled:
eas.json
{
  "build": {
    "development": {
      "ios": {
        "simulator": true
      }
    }
  }
}
2

Download the build

If using EAS Build:
eas build:list --profile development --platform ios
Download the .tar.gz file from the build URL.
3

Install on simulator

# Extract and install
tar -xvf app.tar.gz
xcrun simctl install booted path/to/Your-App.app

# Or drag and drop the .app file onto the simulator

​
iOS Physical Devices

For testing on actual iPhones and iPads, you have several options.
1

Configure for TestFlight

eas.json
{
  "build": {
    "development": {
      "ios": {
        "simulator": false,
        "buildConfiguration": "Release",
        "distribution": "internal"
      }
    }
  },
  "submit": {
    "development": {
      "ios": {
        "appleId": "your-apple-id@example.com",
        "ascAppId": "1234567890",
        "appleTeamId": "YOUR_TEAM_ID"
      }
    }
  }
}
2

Build and submit

# Build for TestFlight
eas build --profile development --platform ios

# Submit to TestFlight
eas submit --platform ios --profile development
3

Invite testers

  1. Go to App Store Connect
  2. Select your app
  3. Go to TestFlight tab
  4. Add internal testers (up to 100)
  5. Testers receive an email invitation
4

Install via TestFlight app

Testers:
  1. Install TestFlight from App Store
  2. Accept invitation email
  3. Install the development build

​
Option 2: Ad-Hoc Distribution

For direct installation without TestFlight:
1

Register devices

# Register a device with EAS
eas device:create
Provide your device UDID. Find it:
  • Connect device to Mac
  • Open Finder > Device > Click serial number
  • Copy UDID
2

Build with registered devices

eas.json
{
  "build": {
    "development": {
      "ios": {
        "simulator": false,
        "distribution": "internal"
      }
    }
  }
}

eas build --profile development --platform ios
3

Download and install

Download the .ipa file and:Using Xcode:
# Connect device via USB
open -a Finder
# Drag .ipa to device in Finder sidebar
Using iOS App Installer:
  1. Download iOS App Installer
  2. Open the .ipa file
  3. Select connected device
  4. Click Install

​
Option 3: Xcode Direct Install

For local development: 
# Build and install in one command
npx expo run:ios --device

# Select your connected device from the list
Xcode handles code signing automatically for development.

​
iOS Development Certificates

For physical device installation, you need:
  1. Apple Developer Account ($99/year for teams, free for personal)
  2. Development Certificate (automatic with Xcode)
  3. Provisioning Profile (automatic with EAS or Xcode)
# Check signing status
eas credentials --platform ios

# Configure new credentials
eas credentials:configure-build --platform ios

​
Android Installation

​
Android Emulator

Emulator installation is straightforward.
1

Start an emulator

# List available emulators
emulator -list-avds

# Start an emulator
emulator @Pixel_7_Pro_API_36 &
Or start from Android Studio > Device Manager.
2

Build and install

# Local build - installs automatically
npx expo run:android

# Or install APK manually
adb install path/to/app.apk

​
Android Physical Devices

Android allows direct APK installation without app store distribution.
1

Enable developer options

On your Android device:
  1. Go to Settings > About Phone
  2. Tap “Build Number” 7 times
  3. Go back to Settings > System > Developer Options
  4. Enable “USB Debugging”
2

Build APK

eas.json
{
  "build": {
    "development": {
      "android": {
        "buildType": "apk",
        "gradleCommand": ":app:assembleDebug"
      }
    }
  }
}

# EAS Build
eas build --profile development --platform android

# Local build
npx expo run:android --variant debug
3

Install via USB

# Connect device via USB
adb devices  # Verify device is connected

# Install APK
adb install path/to/app.apk

# Or install to specific device
adb -s DEVICE_ID install path/to/app.apk

​
Option 2: Download from URL

Share APKs via URL:
1

Get build URL

eas build:list --profile development --platform android
Copy the APK download URL.
2

Install on device

On the Android device:
  1. Open the URL in a browser
  2. Download the APK
  3. Tap the downloaded file
  4. Allow installation from unknown sources if prompted
  5. Tap “Install”

​
Option 3: Internal Distribution

For team distribution:
1

Build AAB for Play Console

eas.json
{
  "build": {
    "development": {
      "android": {
        "buildType": "aab",
        "gradleCommand": ":app:bundleDebug"
      }
    }
  }
}
2

Upload to Play Console

  1. Go to Google Play Console
  2. Select your app
  3. Go to Testing > Internal Testing
  4. Upload the AAB file
  5. Add testers via email

​
Android Signing

Debug builds use automatic debug keystore: 
# View debug keystore info
keytool -list -v -keystore ~/.android/debug.keystore \
  -alias androiddebugkey -storepass android -keypass android
For custom signing: 
# Generate keystore
keytool -genkey -v -keystore my-release-key.keystore \
  -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

# Configure in EAS
eas credentials --platform android

​
Installation via Development Server

Once installed, load JavaScript from the dev server.

​
QR Code Method

1

Start dev server

npx expo start --dev-client
A QR code appears in the terminal.
2

Scan QR code

Open your development build and:
  • iOS: Use camera app or dev client scanner
  • Android: Use dev client scanner

​
Manual URL Entry

# Start with explicit URL
npx expo start --dev-client --host tunnel
In the dev client:
  1. Tap “Enter URL manually”
  2. Enter: exp://YOUR-IP:8081
  3. Tap “Connect”

​
LAN Connection

For local network development: 
# Start on LAN
npx expo start --dev-client --host lan
Requires:
  • Device and computer on same network
  • Firewall allows port 8081
  • No VPN interfering with local network

​
Troubleshooting

​
iOS: App Won’t Install

“Unable to Install App” 
# Check device UDID is registered
eas device:list

# Re-register device
eas device:create

# Rebuild with updated devices
eas build --profile development --platform ios

​
iOS: Untrusted Developer

On device:
  1. Go to Settings > General > VPN & Device Management
  2. Select your developer certificate
  3. Tap “Trust”

​
Android: Installation Blocked

“Install blocked for security”
  1. Go to Settings > Apps > Special Access
  2. Select “Install unknown apps”
  3. Enable for your browser or file manager

​
Android: ADB Not Found

# Add to PATH (macOS/Linux)
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools

# Or use Android Studio's adb
~/Library/Android/sdk/platform-tools/adb devices

​
Can’t Connect to Dev Server

  1. Check firewall: Allow port 8081
  2. Try tunnel mode: npx expo start --tunnel
  3. Verify same network: Device and computer on same WiFi
  4. Check URL: Should be exp://IP:8081 not http://
# Test connectivity
ping YOUR-COMPUTER-IP

# Check port is open
nc -zv YOUR-COMPUTER-IP 8081

​
Build Expires (iOS TestFlight)

TestFlight builds expire after 90 days: 
# Upload new build
eas build --profile development --platform ios
eas submit --platform ios

​
Managing Multiple Builds

​
Build Channels

Test different versions simultaneously:
eas.json
{
  "build": {
    "development": {
      "channel": "development"
    },
    "staging": {
      "channel": "staging",
      "developmentClient": true
    }
  }
}

# Build for different channels
eas build --profile development
eas build --profile staging

# Load specific channel in app
# Dev client shows available channels

​
Build Versions

Track builds with version numbers:
app.json
{
  "expo": {
    "version": "1.0.0",
    "ios": {
      "buildNumber": "1"
    },
    "android": {
      "versionCode": 1
    }
  }
}
Auto-increment with EAS:
eas.json
{
  "build": {
    "development": {
      "ios": {
        "autoIncrement": "buildNumber"
      },
      "android": {
        "autoIncrement": "versionCode"
      }
    }
  }
}

​
Next Steps

Start Debugging

Learn how to debug your development build

Dev Tools

Explore the dev tools and inspector

Testing

Set up automated testing

Error Handling

Handle errors in development

Build docs developers (and LLMs) love

Get started for freeTalk to us