Run on iOS

Install dependencies, install pods, start Metro, and run a React Native app on an iOS simulator or device.

This guide shows how to run a React Native app on an iOS simulator or physical device. It applies to any React Native project with an ios/ folder.

Quick Answer

From the app folder, install dependencies with corepack yarn install, install pods with bundle exec pod install --project-directory=ios, start Metro with corepack yarn start, then run the app with corepack yarn ios.

Prerequisites

Before running iOS, confirm that you have:

  • macOS;
  • Xcode installed and opened at least once;
  • Command Line Tools selected in Xcode settings;
  • Node and a package manager configured;
  • CocoaPods available through Bundler or installed directly;
  • an iOS simulator or a connected iOS device.

If your machine isn't ready yet, start with Set Up Your Development Environment.

1. Open the App Folder

Run commands from the React Native app folder, the one that contains:

package.json
ios/
android/
src/

If a repository contains more than one app, open the specific app you want to run.

2. Install Dependencies

If the project includes .nvmrc, run nvm use first. Then:

corepack enable
corepack yarn install

3. Install iOS Pods

If the project includes a Gemfile, prefer Bundler so everyone uses the same CocoaPods version:

bundle install
bundle exec pod install --project-directory=ios

If there's no Gemfile, run CocoaPods directly:

cd ios
pod install
cd ..

This creates or updates the Xcode workspace used by the iOS build.

4. Start Metro

Start the bundler in one terminal and leave it running while you develop:

corepack yarn start

If it serves stale files, restart with:

corepack yarn start --reset-cache

5. Run the iOS App

In a second terminal:

corepack yarn ios

To choose a specific simulator:

corepack yarn ios --simulator "iPhone 16"

Simulator names depend on your installed Xcode version and runtimes. Check Xcode's Devices and Simulators window for exact names.

6. Open the App in Xcode

For signing, capabilities, entitlements, or detailed build logs, open the workspace (not the .xcodeproj):

open ios/*.xcworkspace

7. Run on a Physical Device

  1. Connect the device to your Mac.
  2. Trust the computer on the device.
  3. Open the workspace in Xcode.
  4. Select the device as the run target.
  5. Choose your signing team under Signing & Capabilities.
  6. Build and run.

Physical devices require valid signing and a bundle identifier that belongs to your Apple Developer account.

Common Issues

Xcode cannot find Node some projects support ios/.xcode.env.local for a local Node path override. Create it on your machine only, and don't commit it:

export NODE_BINARY=$(which node)

Pods are out of sync reinstall pods after any native dependency change, then rebuild:

bundle exec pod install --project-directory=ios

Metro isn't running start it manually with corepack yarn start, or use --reset-cache if the app shows stale code.

Xcode build data is stale clean the build folder from Xcode, or delete Derived Data from Xcode settings, then rebuild.

Verification Checklist

  • corepack yarn install completes;
  • pods install successfully;
  • corepack yarn start starts Metro;
  • corepack yarn ios builds and opens the simulator;
  • the app launches without a startup error screen;
  • Xcode can open the workspace.

Next Steps