run-android - React Native

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

Option	Description	Default
`--simulator <string>`	Device name to launch (simulator or device)	First available
`--device <string>`	Run on a specific device by name	Auto-detect
`--deviceId <string>`	Run on a specific device by ID	Auto-detect
`--variant <string>`	Build variant to run	`debug`
`--appId <string>`	App ID to launch	From `app.json`
`--appIdSuffix <string>`	Custom suffix for app ID	None
`--main-activity <string>`	Main activity name	`MainActivity`
`--port <number>`	Metro bundler port	`8081`
`--tasks <string>`	Gradle tasks to run	`installDebug`
`--no-packager`	Don’t start Metro bundler	`false`
`--verbose`	Show verbose output	`false`
`--mode <string>`	Build mode (debug/release)	`debug`
`--active-arch-only`	Build only for device architecture	`false`

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

Start Android emulator

Open Android Studio > AVD Manager > Start emulatorOr from command line:

emulator -avd Pixel_5_API_33

Run the app

npx react-native run-android

Development with Physical Device

Enable USB Debugging

On your Android device:

Go to Settings > About phone
Tap Build number 7 times
Go to Settings > Developer options
Enable USB debugging

Connect device

Connect via USB and verify:

adb devices

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

Fast Builds
Smaller APK

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

Enable Proguard and enable separate APKs per architecture in android/app/build.gradle:

def enableSeparateBuildPerCPUArchitecture = true
def enableProguardInReleaseBuilds = 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

​Usage

​Options

​Examples

​Basic Usage

​Specific Device

​List Devices

​Run on Specific Device ID

​Release Build

​Custom Variant

​Custom Metro Port

​Without Packager

​Verbose Output

​Fast Build for Device

​Build Variants

​Debug

​Release

​Custom Variants

​Common Workflows

​First Time Setup

​Development with Physical Device

​Testing Release Build

​Environment Variables

​Android SDK Location

​Gradle Options

​Troubleshooting

​SDK Not Found

​Device Not Detected

​Build Failed

​Metro Connection Failed

​Build Too Slow

​Installed Build is Old

​Build Configuration

​Signing Release Build

​Performance Tips

​Next Steps

Build Android

Android Logs

Running on Device

Android Setup

Usage

Options

Examples

Basic Usage

Specific Device

List Devices

Run on Specific Device ID

Release Build

Custom Variant

Custom Metro Port

Without Packager

Verbose Output

Fast Build for Device

Build Variants

Debug

Release

Custom Variants

Common Workflows

First Time Setup

Development with Physical Device

Testing Release Build

Environment Variables

Android SDK Location

Gradle Options

Troubleshooting

SDK Not Found

Device Not Detected

Build Failed

Metro Connection Failed

Build Too Slow

Installed Build is Old

Build Configuration

Signing Release Build

Performance Tips

Next Steps