run-ios - React Native

The run-ios command builds your iOS app and runs it on a simulator or connected device.

Usage

npx react-native run-ios [options]

This command is only available on macOS with Xcode installed.

Options

Option	Description	Default
`--simulator <string>`	Simulator name to launch	`iPhone 15`
`--device <string>`	Run on a connected device by name	None
`--udid <string>`	Run on device with specific UDID	None
`--scheme <string>`	Xcode scheme to build	App name
`--configuration <string>`	Build configuration	`Debug`
`--mode <string>`	Build mode (Debug/Release)	`Debug`
`--port <number>`	Metro bundler port	`8081`
`--terminal <string>`	Terminal app to launch Metro	Default
`--no-packager`	Don’t start Metro bundler	`false`
`--verbose`	Show verbose build output	`false`
`--xcconfig <path>`	Custom xcconfig file	None
`--buildFolder <path>`	Custom build folder	`ios/build`
`--interactive`	Run in interactive mode	`false`

Examples

Basic Usage

npx react-native run-ios

Builds and runs on the default iPhone simulator.

Specific Simulator

npx react-native run-ios --simulator "iPhone 15 Pro"

List available simulators:

xcrun simctl list devices

iPad Simulator

npx react-native run-ios --simulator "iPad Pro (12.9-inch)"

Specific iOS Version

npx react-native run-ios --simulator "iPhone 14 Pro" --udid <simulator-udid>

Physical Device

npx react-native run-ios --device "John's iPhone"

Running on a physical device requires:

Apple Developer account
Device registered in Xcode
Valid provisioning profile

Release Build

npx react-native run-ios --mode Release

Or using configuration:

npx react-native run-ios --configuration Release

Custom Scheme

npx react-native run-ios --scheme MyApp-Staging

Useful when you have multiple schemes in Xcode.

Custom Metro Port

npx react-native run-ios --port 8088

Without Packager

npx react-native run-ios --no-packager

Use when Metro is already running.

Verbose Output

npx react-native run-ios --verbose

Shows detailed Xcode build logs.

Build Configurations

Debug (Default)

npx react-native run-ios --configuration Debug

Developer menu enabled
Fast Refresh enabled
Connects to Metro bundler
Not optimized

Release

npx react-native run-ios --configuration Release

Optimized build
JavaScript bundled in app
No developer tools
Requires signing

Common Workflows

First Time Setup

Install CocoaPods dependencies

cd ios
pod install
cd ..

Run on simulator

npx react-native run-ios

Running on Physical Device

Open in Xcode

open ios/YourApp.xcworkspace

Configure signing

Select your project in the navigator
Select your target
Go to Signing & Capabilities
Select your Team
Ensure Automatically manage signing is checked

Connect device

Connect your iPhone/iPad via USB and trust the computer.

Run the app

npx react-native run-ios --device

Using Multiple Schemes

If you have multiple schemes (e.g., Development, Staging, Production):

# Development
npx react-native run-ios --scheme MyApp-Development

# Staging
npx react-native run-ios --scheme MyApp-Staging

# Production
npx react-native run-ios --scheme MyApp-Production --configuration Release

Device Selection

List Available Simulators

xcrun simctl list devices available

Output:

-- iOS 17.2 --
    iPhone 15 (ABC123...)
    iPhone 15 Plus (DEF456...)
    iPhone 15 Pro (GHI789...)
    iPhone 15 Pro Max (JKL012...)
    iPad Pro (11-inch) (MNO345...)

List Connected Devices

instruments -s devices

Run on Specific UDID

npx react-native run-ios --udid ABC123-DEF456-GHI789

Environment Variables

Custom Port

RCT_METRO_PORT=8088 npx react-native run-ios

Skip Pod Install

NO_FLIPPER=1 npx react-native run-ios

Troubleshooting

Command Not Found

Error: Command 'run-ios' not found Solution: Ensure you’re in a React Native project directory and have installed dependencies:

npm install

Xcode Not Found

Error: xcodebuild: error: SDK "iphoneos" cannot be located Solution:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

CocoaPods Not Installed

Error: CocoaPods is not installed Solution:

sudo gem install cocoapods
cd ios && pod install && cd ..

Simulator Won’t Launch

Error: Simulator specified not found Solution:

# List available simulators
xcrun simctl list devices

# Use exact name
npx react-native run-ios --simulator "iPhone 15 Pro"

Build Failed

Error: Various build errors Solution:

# Clean build
cd ios
rm -rf build
xcodebuild clean -workspace YourApp.xcworkspace -scheme YourApp
cd ..

# Reinstall pods
cd ios
rm -rf Pods Podfile.lock
pod install
cd ..

# Try again
npx react-native run-ios

Cannot Connect to Metro

Error: Red screen “Could not connect to development server” Solution:

# Ensure Metro is running
npx react-native start --reset-cache

# In another terminal
npx react-native run-ios

Signing Errors

Error: Code signing is required Solution:

Open ios/YourApp.xcworkspace in Xcode
Select your target
Go to Signing & Capabilities
Select your development team
Let Xcode automatically manage signing

Module Not Found

Error: Unable to resolve module Solution:

# Clear Metro cache
npx react-native start --reset-cache

# Clear watchman
watchman watch-del-all

# Reinstall dependencies
rm -rf node_modules
npm install
cd ios && pod install && cd ..

Xcode Configuration

Custom Build Settings

Edit ios/YourApp.xcconfig:

ios/YourApp.xcconfig

OTHER_LDFLAGS = $(inherited) -ObjC
HEADER_SEARCH_PATHS = $(inherited) $(SRCROOT)/../node_modules

Multiple Configurations

In Xcode:

Select project > Info tab
Under Configurations, duplicate Debug or Release
Rename to your configuration (e.g., “Staging”)
Run with:

npx react-native run-ios --configuration Staging

Performance Tips

Faster Builds

Enable Xcode’s new build system in Xcode preferences.Also consider:

# Skip installing Flipper (if not needed)
NO_FLIPPER=1 cd ios && pod install && cd ..

Reduce App Size

Use Release configuration which includes optimizations:

npx react-native run-ios --mode Release

Parallel Builds

Add to your Xcode build settings:

SWIFT_COMPILATION_MODE = wholemodule

Advanced Usage

Custom Build Folder

npx react-native run-ios --buildFolder ./custom-build

Interactive Mode

npx react-native run-ios --interactive

Allows selecting device from a list.

Custom Terminal for Metro

npx react-native run-ios --terminal iTerm

Next Steps

Build iOS

Build IPA for TestFlight or App Store

iOS Logs

View device logs for debugging

Running on Device

Complete guide for physical devices

iOS Setup

Configure iOS development environment

​Usage

​Options

​Examples

​Basic Usage

​Specific Simulator

​iPad Simulator

​Specific iOS Version

​Physical Device

​Release Build

​Custom Scheme

​Custom Metro Port

​Without Packager

​Verbose Output

​Build Configurations

​Debug (Default)

​Release

​Common Workflows

​First Time Setup

​Running on Physical Device

​Using Multiple Schemes

​Device Selection

​List Available Simulators

​List Connected Devices

​Run on Specific UDID

​Environment Variables

​Custom Port

​Skip Pod Install

​Troubleshooting

​Command Not Found

​Xcode Not Found

​CocoaPods Not Installed

​Simulator Won’t Launch

​Build Failed

​Cannot Connect to Metro

​Signing Errors

​Module Not Found

​Xcode Configuration

​Custom Build Settings

​Multiple Configurations

​Performance Tips

​Advanced Usage

​Custom Build Folder

​Interactive Mode

​Custom Terminal for Metro

​Next Steps

Build iOS

iOS Logs

Running on Device

iOS Setup

Usage

Options

Examples

Basic Usage

Specific Simulator

iPad Simulator

Specific iOS Version

Physical Device

Release Build

Custom Scheme

Custom Metro Port

Without Packager

Verbose Output

Build Configurations

Debug (Default)

Release

Common Workflows

First Time Setup

Running on Physical Device

Using Multiple Schemes

Device Selection

List Available Simulators

List Connected Devices

Run on Specific UDID

Environment Variables

Custom Port

Skip Pod Install

Troubleshooting

Command Not Found

Xcode Not Found

CocoaPods Not Installed

Simulator Won’t Launch

Build Failed

Cannot Connect to Metro

Signing Errors

Module Not Found

Xcode Configuration

Custom Build Settings

Multiple Configurations

Performance Tips

Advanced Usage

Custom Build Folder

Interactive Mode

Custom Terminal for Metro

Next Steps