Article

Running Your App in the Simulator or on a Device

Launch your app in a simulated iOS, tvOS, or watchOS device or on a device connected to your Mac.

Overview

After you create a project, you can build and run your app on a simulated or real device without needing to lay out the user interface or write code. You may connect a real device to your Mac using a cable, or for iOS or tvOS apps, connect it over WiFi after you pair it with Xcode. For macOS apps, choose a scheme, then click the Run button in the toolbar.

Screenshot of the toolbar in the main window that shows the buttons for controlling execution, choosing the scheme and run destination, viewing the activity of the build, opening the library and configuring the editor area.

You can also run SwiftUI apps in the simulator or on a device using the controls in the preview. For more details, see Creating Your App's Interface with SwiftUI.

Choose a Scheme

A scheme is a collection of settings that specify the targets to build, the build configuration, and the executable environment for an app. There's a scheme for each product (app, library, or framework) in your project. For projects that build an app, choose the scheme that matches your app's name from the scheme menu in the toolbar. For watchOS apps, choose the WatchKit App target as the scheme.

Screenshot of the scheme menu in the toolbar.

To learn more about schemes, go to Configure schemes in Xcode Help.

Select a Simulated Device

For iOS, tvOS, and watchOS apps, you can choose a simulated device, under [Platform] Simulators, from the run destination menu next to the scheme menu in the toolbar.

Screenshot showing the run destination menu in the toolbar where you choose a real device, choose a simulated device, or create a custom simulator.

To add additional simulators of a product family running older versions of the operating system, choose Add Additional Simulators.

Select a Real Device

Before you distribute your app, launch it on a real device. Connect the device to your Mac, and choose the device in the run destination menu. For macOS versions of an iPad app, choose My Mac (the Mac running Xcode) as the device.

If you choose a real device, add your Apple ID in Accounts preferences and assign the project to a team on the Signing & Capabilities pane of the project editor. A single individual constitutes a one-person team. For macOS apps, you need to code sign the app if you enable certain capabilities. If you belong to the Apple Developer Program, you need to register the device before you can run the app.

You can also run iOS and tvOS apps on a wireless device if you pair the device with Xcode. For example, you can pair an Apple TV that's already on your network with Xcode so it appears as a run destination in the toolbar. For watch-only apps, you can run the watchOS app over the paired iOS device.

For more details on capabilities and code signing, see Adding Capabilities to Your App.

Run the App

Click the Run button to build and run the app on the selected simulated or real device. 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.

Screenshot showing the debug area controls to set breakpoints, control execution, show the view hierarchy, show the memory graph, override environment settings, and view threads.

If you choose a simulated device as the run destination, the Simulator launches and displays a simulation of the device family you chose. For watchOS apps, only the Apple Watch simulator appears, regardless of whether it's dependent on an iOS app. For how to interact with a simulated device, go to Simulator Help.

Screenshot of iPhone, Apple Watch, and Apple TV simulators.

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 > Show Issue Navigator to view the messages.

When you're done testing the app, click the Stop button in the toolbar.