Skip to main content
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

OptionDescriptionDefault
--simulator <string>Simulator name to launchiPhone 15
--device <string>Run on a connected device by nameNone
--udid <string>Run on device with specific UDIDNone
--scheme <string>Xcode scheme to buildApp name
--configuration <string>Build configurationDebug
--mode <string>Build mode (Debug/Release)Debug
--port <number>Metro bundler port8081
--terminal <string>Terminal app to launch MetroDefault
--no-packagerDon’t start Metro bundlerfalse
--verboseShow verbose build outputfalse
--xcconfig <path>Custom xcconfig fileNone
--buildFolder <path>Custom build folderios/build
--interactiveRun in interactive modefalse

​
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

1

Install CocoaPods dependencies

cd ios
pod install
cd ..
2

Run on simulator

npx react-native run-ios

​
Running on Physical Device

1

Open in Xcode

open ios/YourApp.xcworkspace
2

Configure signing

  1. Select your project in the navigator
  2. Select your target
  3. Go to Signing & Capabilities
  4. Select your Team
  5. Ensure Automatically manage signing is checked
3

Connect device

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

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:
  1. Open ios/YourApp.xcworkspace in Xcode
  2. Select your target
  3. Go to Signing & Capabilities
  4. Select your development team
  5. 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:
  1. Select project > Info tab
  2. Under Configurations, duplicate Debug or Release
  3. Rename to your configuration (e.g., “Staging”)
  4. Run with:
npx react-native run-ios --configuration Staging

​
Performance Tips

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 ..
Use Release configuration which includes optimizations:
npx react-native run-ios --mode Release
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

Build docs developers (and LLMs) love

Get started for freeTalk to us