Running your app in Simulator or on a device
Launch your app in a simulated iOS, iPadOS, tvOS, visionOS, or watchOS device, or on a device connected to a Mac.
Overview
To test your app, build and run it on a simulated or real device. Use simulated devices to debug your app on a variety of hardware to which you don’t have immediate access. The tradeoff is that simulated devices run within the Simulator app on your Mac and don’t replicate the performance or features of an actual device. To verify that your app runs exactly as intended, run it on one or more real devices. You can connect a real device to your Mac using a cable, or connect it over Wi-Fi after you pair it with Xcode.
Xcode previews let you see your app’s interface without building and running your app. For more information, see Previewing your app’s interface in Xcode.
Select a build scheme and run destination
Before you build and run your app, select a build scheme that includes the target for your app. A scheme is a collection of project details and settings that tell Xcode how to build and run a product from your project. Xcode determines where the resulting product can run based on the scheme you select, and populates the run destination menu in the toolbar with the list of available devices. For example, if the scheme contains a tvOS app, Xcode includes only tvOS simulators and devices as potential run destinations.
If you don’t have platform support installed for your target, you can’t build and run your app on a device. To install platform support, click the Get button that appears next to the Any [Platform] Device run destination. Alternatively, manage your downloads later in Components settings (see Downloading and installing additional Xcode components).
To learn more about schemes, see Customizing the build schemes for a project.
Configure the list of simulated devices
Manage real and simulated devices in the Devices and Simulators window in Xcode. To view this window, choose Window > Devices and Simulators. To view the available simulated devices, click the Simulators tab in the sidebar.
[Image]
To add a new simulated device, click the Add button (+) at the bottom of the list of simulators and specify the configuration you want. You can add new simulators to specify a different device type or operating system version than the default set. To remove a simulator from the list, select it and press Delete.
Connect real devices to your Mac
To manage connections to your real devices, choose the Devices tab in the Devices and Simulators window in Xcode. The Devices tab shows the connected and disconnected devices along with other devices it detects.
Select a device in the sidebar to view the status and other information in the detail area on the right. If there’s a connection issue, Xcode displays an alert in a yellow box at the top of the detail area. For example, Xcode might show a device as unavailable if it’s not running an operating system version your app supports, or you need to download an SDK that matches the operating system version on the device.
Xcode automatically starts pairing new devices that you connect to your Mac with an appropriate cable. For complete steps to pair different types of devices, see Pairing your devices with Xcode.
After Xcode finishes pairing a device, it appears under Connected in the Devices and Simulators window sidebar. If your device is connected to the same Wi-Fi network as your Mac, Xcode can use that connection to install apps instead of a physical connection.
Before running your app on a real device, perform a few additional steps to create a development provisioning profile:
In Xcode > Settings > Apple Accounts, add your Apple Developer Program or personal account.
In the Signing & Capabilities pane of the project editor, assign your project to a team.
In the toolbar of the project editor, choose the real device as the run destination.
With the default “Automatically manage signing” option enabled, Xcode registers the device and creates the development provisioning profile for you. Otherwise, click the Register button under Signing on the Signing & Capabilities pane if it appears.
For more information on developer accounts, see Choosing a Membership.
Run the app
To build and run the app on the selected simulated or real device, click the Run button in the toolbar or choose Product > Run. View the status of the build in the activity area of the toolbar.
If the build is successful, Xcode runs the app and opens a debugging session in the debug area. Use the controls in the debug area to step through your code, inspect variables, and interact with the debugger. To run the app without the debugger, turn off the Debug executable option in the Info tab of the scheme editor.
If the build is unsuccessful, click the indicators in the activity area to read the error or warning messages in the Issue navigator. Alternatively, choose View > Navigators > Issues to view the messages.
When you’re done testing the app, click the Stop button in the toolbar.
Interact with the simulated environment
If you choose a simulated device as the run destination, Simulator launches and displays a window that corresponds to the simulated environment. For some devices, Simulator surrounds the screen content with a shell that resembles the target device. In visionOS, it displays a synthetic space to mimic the experience someone would have when they wear the device.
Each device shell and space has specific controls to support interactions. For device-specific details, see the reference on interactions.