> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paperline.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulators & Devices

> Test your iOS app on iPhone Simulator or physical devices. Paperline automatically configures iOS runtime and creates simulators.

## iOS Simulator

The iOS Simulator is a virtual iPhone or iPad that runs on your Mac. It's the fastest way to test your app during development.

### What is a Simulator?

Simulators are virtual iOS devices provided by Apple as part of Xcode. They let you run and test your app without a physical device. Each simulator mimics a specific iPhone or iPad model.

### How Simulators Work

Simulators require two components:

1. **iOS Runtime** — The iOS operating system version (e.g., iOS 26)
2. **Simulator Device** — A virtual device using that runtime (e.g., iPhone 17 Pro)

### Installing via Paperline Doctor

Paperline Doctor automatically installs everything you need:

1. Downloads the latest iOS runtime
2. Creates an iPhone 17 Pro simulator

See [Development Environment](/getting-started/development-environment) for details.

### Manual Installation

If you need additional simulators or runtimes:

1. Open **Xcode → Settings → Platforms**
2. Click **+** to download additional iOS versions
3. Open **Window → Devices and Simulators**
4. Click **+** under Simulators to create new devices

### Using Simulators in Paperline

1. Click the device selector in the toolbar
2. Choose a simulator from the list
3. Your app builds and runs on that simulator

## Physical Devices

You can also run your app on a real iPhone or iPad.

### Requirements

* iPhone or iPad running iOS 18+
* USB cable or same Wi-Fi network
* Apple Developer account (free or paid)

### Connecting a Device

1. Connect your device via USB
2. Trust your Mac when prompted on the device
3. The device appears in Paperline's device selector
4. Select it to build and run

## Simulator vs Physical Device

| Feature             | Simulator     | Physical Device |
| ------------------- | ------------- | --------------- |
| Speed               | Faster builds | Slower builds   |
| Camera              | No            | Yes             |
| Sensors             | Limited       | Full access     |
| Push Notifications  | No            | Yes             |
| Performance Testing | Approximate   | Accurate        |
| Requires Apple ID   | No            | Yes             |

## Troubleshooting

<AccordionGroup>
  <Accordion title="No simulators available">
    iOS runtime may not be installed:

    1. Run Paperline Doctor and click "Install" for iPhone Simulator & iOS Version
    2. Or manually: **Xcode → Settings → Platforms → iOS**
  </Accordion>

  <Accordion title="Simulator not appearing after install">
    1. Quit and reopen Paperline 2. Check **Xcode → Window → Devices and Simulators** 3. Create a new simulator if the
       list is empty
  </Accordion>

  <Accordion title="Physical device not recognized">
    1. Disconnect and reconnect the USB cable 2. Unlock the device and tap "Trust" when prompted 3. Check that Xcode sees
       the device in **Window → Devices and Simulators**
  </Accordion>

  <Accordion title="Build fails on physical device">
    Usually a code signing issue:

    1. Open the project in Xcode
    2. Go to **Signing & Capabilities**
    3. Select your development team
    4. Try building again in Paperline
  </Accordion>
</AccordionGroup>