xref: /expo/docs/pages/workflow/ios-simulator.mdx (revision cedf99eb) 
1---
2title: iOS Simulator
3description: Learn how you can install the iOS simulator on your Mac and use it for developing your app.
4---
5
6import ImageSpotlight from '~/components/plugins/ImageSpotlight';
7import Video from '~/components/plugins/Video';
8import { Terminal } from '~/ui/components/Snippet';
9import { Step } from '~/ui/components/Step';
10
11It's often convenient to develop your app directly on your computer rather than having to physically interact with an iPhone and iPad and load your app over the network, which may be slow under some conditions such as if you need to use a tunnel connection because LAN isn't possible on your network.
12
13This guide explains how you can install the iOS simulator on your Mac and use it for developing your app. It is not possible to install the iOS Simulator on any operating system except macOS. If you want to develop an app for iOS from a Windows machine then you will need to use a physical iOS device.
14
15<Step label="1">
16## Install Xcode
17
18Open up the Mac App Store, search for [Xcode](https://apps.apple.com/us/app/xcode/id497799835), and hit install (or update if you have it already).
19If you're unable to update, it is because your operating system might be out of date. We recommend updating your operating system to the latest version and then updating Xcode.
20You 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.
21
22</Step>
23
24<Step label="2">
25## Install Xcode Command Line Tools
26
27Open Xcode, then choose **Preferences...** from the Xcode menu (or press <kbd>Cmd ⌘</kbd> + <kbd>,</kbd>). Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.
28
29<ImageSpotlight alt="Xcode preferences" src="/static/images/xcode-command-line.png" />
30</Step>
31
32<Step label="3">
33## Try it out
34
35Run your app with `npx expo start` and press <kbd>I</kbd> from the command line.
36
37You may get a warning about needing to accept the Xcode license. Run the command that it suggests. Open your app again to see if it was successful.
38If not, check the [troubleshooting](#troubleshooting) tips below.
39
40If the troubleshooting tips are not helpful, seek help on [Expo Development Tools section of the forums](https://forums.expo.dev/c/expo-dev-tools), Stack Overflow, or Google.
41
42<Video file="open-in-ios-simulator.mp4" />
43
44> **Pro Tip:** Press <kbd>Shift</kbd> + <kbd>I</kbd> in the CLI UI to interactively select a simulator to open.
45
46</Step>
47
48## Limitations
49
50Although the iOS simulator is great for rapid development, it does come with a few limitations. [Apple's documentation](https://help.apple.com/simulator/mac/current/#/devb0244142d) goes into more detail, but we'll list out a few of the main differences that affect Expo APIs here.
51
52The following hardware is unavailable in Simulator:
53
54- Audio Input
55- Barometer
56- Camera
57- Motion Support (accelerometer and gyroscope)
58
59It should also be noted that Simulator suspends background apps and processes on iOS 11 and later.
60
61## Troubleshooting
62
63### The CLI seems to be stuck when opening a Simulator
64
65Sometimes the iOS simulator doesn't respond to the open command. If it seems stuck on this prompt, you can open the iOS simulator manually (`open -a Simulator`) and then in the macOS toolbar, choose **Hardware** &rarr; **Device**, and select an iOS version and device that you'd like to open.
66
67<ImageSpotlight
68  alt="Hardware > Device toolbar in Xcode"
69  src="/static/images/open-simulator-manually.png"
70/>
71
72You 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 target the most recently opened simulator.
73
74### The simulator opened but the Expo Go app isn't opening inside of it
75
76The first time you install the app in the simulator, iOS will ask if you'd like to open the Expo Go app. You may need to interact with the simulator (click around, drag something) for this prompt to show up, then press `OK`.
77
78### How do I force an update to the latest version?
79
80Create a project with the desired SDK version and open it in a simulator to install a particular version of Expo Go.
81
82<Terminal
83  cmd={[
84    '# Bootstrap an SDK 48 project',
85    '$ npx create-expo-app --template blank@48',
86    '',
87    '# Open the app on a simulator to install the required Expo Go app',
88    '$ npx expo start --ios',
89  ]}
90/>
91
92### Expo CLI is printing an error message about xcrun, what do I do?
93
94For miscellaneous errors, try the following:
95
96- Manually uninstall Expo Go on your simulator and reinstall by pressing <kbd>Shift</kbd> + <kbd>I</kbd> in the Expo CLI Terminal UI and selecting the desired simulator.
97- If that doesn't help, focus the simulator window and in the Mac toolbar choose **Hardware** &rarr; **Erase All Content and Settings...**<br/>
98  This will reinitialize your simulator from a blank image. This is sometimes useful for cases where your computer is low on memory and the simulator fails to store some internal files, leaving the device in a corrupt state.
99