Skip to main content
The run-android command builds your Android app and runs it on a connected device or emulator.

​
Usage

npx react-native run-android [options]
Make sure you have an Android emulator running or a device connected via USB with USB debugging enabled.

​
Options

OptionDescriptionDefault
--simulator <string>Device name to launch (simulator or device)First available
--device <string>Run on a specific device by nameAuto-detect
--deviceId <string>Run on a specific device by IDAuto-detect
--variant <string>Build variant to rundebug
--appId <string>App ID to launchFrom app.json
--appIdSuffix <string>Custom suffix for app IDNone
--main-activity <string>Main activity nameMainActivity
--port <number>Metro bundler port8081
--tasks <string>Gradle tasks to runinstallDebug
--no-packagerDon’t start Metro bundlerfalse
--verboseShow verbose outputfalse
--mode <string>Build mode (debug/release)debug
--active-arch-onlyBuild only for device architecturefalse

​
Examples

​
Basic Usage

npx react-native run-android
Builds debug variant and runs on the first available device/emulator.

​
Specific Device

npx react-native run-android --device "Pixel 5"
Runs on a device named “Pixel 5”.

​
List Devices

adb devices
Outputs: 
List of devices attached
emulator-5554   device
3FEDA8BC0      device

​
Run on Specific Device ID

npx react-native run-android --deviceId emulator-5554

​
Release Build

npx react-native run-android --mode release
Builds and runs the release variant (useful for testing production builds).

​
Custom Variant

npx react-native run-android --variant staging
Runs a custom build variant defined in your build.gradle.

​
Custom Metro Port

npx react-native run-android --port 8088

​
Without Packager

npx react-native run-android --no-packager
Use this when Metro is already running in another terminal.

​
Verbose Output

npx react-native run-android --verbose
Shows detailed Gradle build output for debugging.

​
Fast Build for Device

npx react-native run-android --active-arch-only
Builds only for the connected device’s architecture, significantly speeding up builds.

​
Build Variants

By default, React Native creates these variants:

​
Debug

npx react-native run-android --variant debug
  • Developer menu enabled
  • Remote debugging enabled
  • Not optimized or minified
  • Connects to Metro bundler

​
Release

npx react-native run-android --variant release
  • Optimized and minified
  • No developer tools
  • Requires signing configuration
  • Uses bundled JavaScript

​
Custom Variants

Define custom variants in android/app/build.gradle:
android/app/build.gradle
android {
    buildTypes {
        staging {
            matchingFallbacks = ['debug', 'release']
            applicationIdSuffix ".staging"
            debuggable true
            minifyEnabled false
        }
    }
}
Run with: 
npx react-native run-android --variant staging

​
Common Workflows

​
First Time Setup

1

Start Android emulator

Open Android Studio > AVD Manager > Start emulatorOr from command line:
emulator -avd Pixel_5_API_33
2

Run the app

npx react-native run-android

​
Development with Physical Device

1

Enable USB Debugging

On your Android device:
  1. Go to Settings > About phone
  2. Tap Build number 7 times
  3. Go to Settings > Developer options
  4. Enable USB debugging
2

Connect device

Connect via USB and verify:
adb devices
3

Run the app

npx react-native run-android

​
Testing Release Build

# Build and install release variant
npx react-native run-android --mode release

# App will use bundled JavaScript, not Metro

​
Environment Variables

​
Android SDK Location

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

​
Gradle Options

export GRADLE_OPTS="-Xmx4096m -XX:MaxPermSize=512m"
npx react-native run-android

​
Troubleshooting

​
SDK Not Found

Error: SDK location not found Solution: Create android/local.properties: 
sdk.dir=/Users/username/Library/Android/sdk

​
Device Not Detected

Error: No connected devices Solution: 
# Check ADB connection
adb devices

# Restart ADB server
adb kill-server
adb start-server

# Enable USB debugging on device

​
Build Failed

Error: Execution failed for task ':app:installDebug' Solution: 
# Clean build
cd android
./gradlew clean
cd ..

# Run again
npx react-native run-android

​
Metro Connection Failed

Error: Red screen “Unable to load script” Solution: 
# Reverse ADB port
adb reverse tcp:8081 tcp:8081

# Reload app
adb shell input keyevent 82  # Open developer menu
# Select "Reload"

​
Build Too Slow

Solution: Add to android/gradle.properties: 
org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.configureondemand=true
org.gradle.jvmargs=-Xmx4096m -XX:MaxPermSize=512m
Or use active arch only: 
npx react-native run-android --active-arch-only

​
Installed Build is Old

Solution: 
# Uninstall old version
adb uninstall com.yourapp

# Run again
npx react-native run-android

​
Build Configuration

​
Signing Release Build

Edit android/app/build.gradle:
android/app/build.gradle
android {
    signingConfigs {
        release {
            storeFile file('my-release-key.keystore')
            storePassword 'password'
            keyAlias 'my-key-alias'
            keyPassword 'password'
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

​
Performance Tips

Use architecture-specific builds:
npx react-native run-android --active-arch-only
Enable Gradle daemon in android/gradle.properties:
org.gradle.daemon=true
org.gradle.parallel=true

​
Next Steps

Build Android

Build APK/AAB for distribution

Android Logs

View device logs for debugging

Running on Device

Complete guide for physical devices

Android Setup

Configure Android development environment

Build docs developers (and LLMs) love

Get started for freeTalk to us