# How `get_booted_device_udid()` Identifies the Active iOS Simulator in ios-simulator-skill

> Learn how get_booted_device_udid() reliably identifies the active iOS simulator using xcrun simctl list and regex for precise UUID extraction.

- Repository: [Conor/ios-simulator-skill](https://github.com/conorluddy/ios-simulator-skill)
- Tags: how-to-guide
- Published: 2026-02-27

---

**The `get_booted_device_udid()` function detects the active iOS simulator by executing `xcrun simctl list devices booted` and extracting the first UUID match using the regex pattern `\(([A-F0-9\-]{36})\)`.**

The `ios-simulator-skill` repository provides automation utilities for managing iOS simulators via command-line tools. At the heart of its device detection logic lies `get_booted_device_udid()`, a utility function that reliably identifies which simulator is currently active without requiring manual UDID input.

## How `get_booted_device_udid()` Detects the Active Simulator

### Executing the simctl Query

The function shells out to Apple's `simctl` utility using Python's `subprocess` module. It runs:

```python
xcrun simctl list devices booted

```

With parameters `capture_output=True`, `text=True`, and `check=True` to ensure the command executes successfully and returns readable output.

### Parsing the Device UUID

The output contains lines like:

```

  iPhone 16 Pro (ABC123-DEF456-7890AB-CDEF12) (Booted)

```

The function applies the regex pattern:

```python
r"\(([A-F0-9\-]{36})\)"

```

This captures the 36-character UUID (including hyphens) wrapped in parentheses. The first match is returned as the active simulator's UDID.

### Handling Edge Cases

If the subprocess call raises `CalledProcessError` or no UUID pattern matches, the function returns `None`. This allows calling functions like `resolve_udid()` to handle the error state appropriately, typically by raising a `RuntimeError` when no booted device is found.

## Implementation Location in device_utils.py

The core logic resides in [`ios-simulator-skill/scripts/common/device_utils.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/scripts/common/device_utils.py) at lines 24-55. This module also exports `resolve_udid()` and `list_simulators()`, which build upon `get_booted_device_udid()` to provide higher-level device management abstractions.

## Practical Code Examples

### Retrieving the Current Simulator UDID

```python
from ios_simulator_skill.scripts.common.device_utils import get_booted_device_udid

udid = get_booted_device_udid()
if udid:
    print(f"Booted simulator UDID: {udid}")
else:
    print("No simulator is currently booted")

```

### Integrating with Command-Line Scripts

```python
import sys
from ios_simulator_skill.scripts.common.device_utils import resolve_udid

def main():
    # Assume args.udid comes from argparse (may be None)

    try:
        device_udid = resolve_udid(args.udid)
        print(f"Using device {device_udid}")
    except RuntimeError as e:
        print(e, file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

```

### Detecting Multiple Booted Simulators

```python
from ios_simulator_skill.scripts.common.device_utils import list_simulators

booted = [d for d in list_simulators(state="booted")]
if len(booted) > 1:
    print("Warning: more than one simulator is booted")
elif booted:
    print(f"Booted UDID: {booted[0]['udid']}")
else:
    print("No booted simulators found")

```

## Summary

- **`get_booted_device_udid()`** executes `xcrun simctl list devices booted` to query the system for active simulators.
- It extracts the device identifier using the regex pattern `r"\(([A-F0-9\-]{36})\)"` to capture the 36-character UUID.
- The function returns `None` when no booted device exists or the command fails, delegating error handling to calling functions like `resolve_udid()`.
- Located in [`ios-simulator-skill/scripts/common/device_utils.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/scripts/common/device_utils.py), this utility serves as the foundation for all automatic device detection in the repository.

## Frequently Asked Questions

### What command does `get_booted_device_udid()` use to find booted simulators?

The function shells out to `xcrun simctl list devices booted`, which returns a formatted list of all currently running iOS simulators along with their metadata and UDIDs.

### How does the function handle cases where no simulator is running?

When the subprocess command fails or the regex fails to match a UUID pattern, `get_booted_device_udid()` returns `None`. This allows calling code to detect the absence of a booted device and respond appropriately, typically by raising a `RuntimeError`.

### Can `get_booted_device_udid()` return multiple UDIDs if several simulators are booted?

No, the function returns only the first UUID match found in the `simctl` output. While `xcrun simctl list devices booted` can list multiple booted devices, this implementation specifically extracts and returns the first one detected, leaving multi-device handling to higher-level functions like `list_simulators()`.

### Where is `get_booted_device_udid()` defined in the ios-simulator-skill repository?

The function is implemented in [`ios-simulator-skill/scripts/common/device_utils.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/scripts/common/device_utils.py) between lines 24 and 55, alongside related utilities such as `resolve_udid()` and `list_simulators()`.