Step 1: Install Xcode

This step is very easy but it takes a while. Open up the Mac App Store, search for Xcode, and hit install (or update if you have it already). If you're not able to update because your operating system is out of date, we recommend updating your operating system to the latest version and then updating Xcode. You may run into issues further down the line if your Xcode version is out of date, for example you may not be able to submit your app to the App Store.

Step 2: Install Xcode Command Line Tools

Open Xcode, then choose "Preferences..." from the Xcode menu (or press ⌘+,). Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Preferences

Step 3: Try it out

Run your app with expo-cli and press i from the command line or Run on iOS simulator from the browser-based DevTools UI. You may get a warning about needing to accept the Xcode license. Run the command that it suggests. Open your app again, success! Or no? If no, please seek help on StackOverflow, Google, or the Expo-CLI section of the forums. The troubleshooting tips below may be helpful too.


The CLI seems to be stuck on "Trying to open the project in iOS simulator..."

Sometimes the iOS simulator doesn't respond to commands to open. If it seems to be stuck on this prompt, you can open the iOS simulator manually (open -a Simulator) and then in the macOS toolbar choose Hardware → Device and select an iOS version and device that you'd like to open.

Xcode Preferences

You can also use this menu to open any version of the simulator that you like. You can open multiple simulators at the same time but expo-cli will always act on the most recently opened on.

The simulator opened but the Expo client app isn't opening inside of it

The first time you install the app in the simulator, iOS will prompt you to ask if you'd like to open the Expo client app. You may need to interact with the simulator (click around, drag something) for this prompt to show up. Press OK when it shows up.

How do I force an update to the latest version?

You can run expo client:install:ios to download and install the latest Expo client version in the simulator.

expo-cli is printing some esoteric error message about xcrun, what do I do?

Run expo client:install:ios again to uninstall and reinstall the Expo client app. If that doesn't help, focus the simulator window and in the Mac toolbar choose Hardware → Erase All Content and Settings... This will reinitialize your simulator from a blank image. Good to go!