iOS Simulator Setup in Xcode: Step-by-Step

This guide walks you through creating, configuring, and launching an iOS Simulator in Xcode for testing your apps. You’ll learn how to add a simulator device, run your project on it, and troubleshoot common setup issues. Before starting, make sure you have the latest stable version of Xcode installed from the Mac App Store and that your Mac meets the system requirements for that version.

What You’ll Need

A Mac running macOS (the latest version supported by your Xcode version)
Xcode installed (from the Mac App Store or Apple Developer site)
An Apple ID (free) to sign in to Xcode if you plan to deploy to a physical device, though not required for simulator-only testing
Enough free disk space (simulators and runtimes can take several gigabytes)

Step-by-Step

Open Xcode and create or open a project. Launch Xcode, then either create a new project (File > New > Project) or open an existing one. For a new project, choose an iOS app template and fill in the project options.
Open the Devices and Simulators window. Go to Window > Devices and Simulators (or press Cmd+Shift+2). This is where you manage all simulators.
Click the “+” button. In the bottom-left corner of the window, click the plus icon to add a new simulator.
Fill in the simulator details. In the dialog that appears, give your simulator a name (e.g., “iPhone 15 Pro – My Test”). Choose a device type (iPhone, iPad, etc.) from the dropdown, and select a runtime (iOS version) from the list. If you don’t see a runtime, you’ll need to download it first (see Step 5).
Download a simulator runtime if needed. If the runtime dropdown is empty or doesn’t have the iOS version you want, click Settings (or go to Xcode > Settings > Components). Find the iOS simulator runtime you need and click the download arrow next to it. Wait for the download to finish, then return to the Devices and Simulators window and refresh the runtime list.
Click “Create”. After filling in the details, click Create. Your new simulator will appear in the list on the left side of the Devices and Simulators window.
Select the simulator as your build target. Back in the main Xcode window, look at the toolbar at the top. There is a dropdown that currently shows something like “My Mac” or a device name. Click it and select your newly created simulator from the list.
Build and run. Press Cmd+R or click the Play button. Xcode will compile your app and launch the simulator automatically. The first launch may take a while as the simulator boots.
Use the simulator. Once the simulator appears, you can interact with it as if it were a real device. Use the mouse to tap, click and drag to swipe, and use the keyboard for text input. The simulator menu bar gives you options like rotating the device, simulating touch gestures, and changing the appearance (light/dark mode).
Stop the app. To stop the app, press Cmd+. or click the Stop button in Xcode. The simulator will stay open for future runs.

Common Mistakes

Forgetting to download the runtime. The most common issue is trying to add a simulator without having the iOS runtime installed. Always check the Components tab in Settings first.
Selecting the wrong scheme. If you have multiple schemes, make sure the active scheme is set to an iOS simulator destination. Sometimes Xcode defaults to “My Mac” which won’t run an iOS app.
Running on a physical device by mistake. If you plug in an iPhone, Xcode may automatically select it as the target. Make sure the dropdown shows the simulator you want.
Not updating Xcode after a macOS update. A new macOS version may require a newer Xcode version, and older Xcode versions might not support the latest simulator runtimes.

Tips

Use multiple simulators. You can create several simulators with different device types and iOS versions to test your app across screen sizes and OS versions. This is especially useful for checking layout compatibility.
Take screenshots easily. In the simulator, use File > Save Screen or press Cmd+S to capture the screen. This is handy for documentation or bug reports.
Simulate location and permissions. The simulator can simulate GPS locations (Features > Location) and you can reset privacy permissions (Device > Erase All Content and Settings) to test the first-run experience.
Use keyboard shortcuts. Learn common shortcuts like Cmd+Shift+H for the home button, Cmd+Left/Right to rotate, and Cmd+Shift+O to toggle the on-screen keyboard.
Keep runtimes updated. Periodically check for new iOS simulator runtimes in Settings > Components to stay current.

Troubleshooting

Simulator doesn’t appear in the target dropdown. First, make sure the Devices and Simulators window shows your simulator. If it does, but the dropdown doesn’t list it, try restarting Xcode. If that fails, go to File > Project Settings (or Workspace Settings) and check the “Build System” and “Scheme” settings. Sometimes a clean build (Shift+Cmd+K) helps.

Simulator boots but the app doesn’t install. This often happens when the app’s deployment target is higher than the simulator’s iOS version. Check your project’s deployment target (in the project settings under “Info”) and ensure it’s equal to or lower than the simulator’s runtime. Also verify that the scheme’s build configuration is set to Debug.

Simulator is very slow. The first boot after a runtime update can be slow. If it’s persistently slow, try erasing the simulator (Device > Erase All Content and Settings) to clear cached data. Also make sure your Mac has enough free RAM and disk space.

Xcode says “Unable to boot the simulator”. This can be caused by a corrupted simulator state. Try quitting the Simulator app and Xcode, then delete the problematic simulator and recreate it. If that doesn’t work, restart your Mac and try again.

Runtime download fails. If the download of a simulator runtime fails, check your internet connection and ensure you have enough disk space. You can also try downloading via the xcodebuild -downloadPlatform iOS command in Terminal.

App crashes on launch in simulator but works on a device. This is rare but can happen due to simulator-specific issues. Try resetting the simulator’s content and settings (Device > Erase All Content and Settings) and then re-run. If the crash persists, check the console output for error messages.

Frequently Asked Questions

Can I test push notifications in the simulator?

Yes, since Xcode 11.4, you can simulate push notifications by dragging a .apns file onto the simulator. You’ll need to set up the notification payload correctly.

How do I change the simulator’s appearance to dark mode?

In the simulator, go to Features > Toggle Appearance or press Cmd+Shift+A. This toggles between light and dark mode.

Can I run multiple simulators at the same time?

Yes, you can launch multiple simulators by selecting different simulator destinations and running the app in each. However, this can be resource-intensive, so it’s best to close unused ones.

How do I uninstall an app from the simulator?

Press and hold the app icon on the home screen until it jiggles, then click the X. Alternatively, you can use Device > Erase All Content and Settings to wipe the simulator.

Why is the simulator not showing my app’s keyboard?

Sometimes the software keyboard doesn’t appear automatically. Toggle it with Cmd+Shift+K or go to I/O > Keyboard > Toggle Software Keyboard.

Can I test ARKit or Metal apps in the simulator?

Yes, the simulator supports ARKit and Metal for basic testing, but performance and features may differ from a physical device. For accurate testing, use a real device.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →