# Which macOS Versions Are Compatible with vphone‑cli?

> Discover which macOS versions are compatible with vphone-cli. Learn why macOS 15 Sequoia or later is required due to Virtualization.framework updates.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: compatibility-guide
- Published: 2026-09-05

---

**vphone‑cli requires macOS 15 (Sequoia) or later because it relies on the Virtualization.framework PV=3 profile and private‑API entitlements introduced in that version.**

vphone‑cli is an open‑source virtualization tool by Lakr233 that creates virtual iPhone environments using Apple’s native hypervisor. Because the implementation depends on specific hardware model profiles and entitlements only exposed in recent macOS releases, system compatibility is strictly enforced at the build, installation, and runtime levels.

## Why macOS 15 Sequoia Is the Minimum Requirement

The tool is built on Apple’s **Virtualization.framework** using the **PV=3** hardware model profile. According to the source code in [`sources/vphone-cli/VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneHardwareModel.swift), this profile requires a minimum host OS version of macOS 15.0. The private APIs necessary for iOS virtualization are not available in earlier macOS releases, making Sequoia a hard dependency.

### Source Code Enforcement

The Lakr233/vphone‑cli repository enforces this constraint across multiple files:

- **[`Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift)**: Declares the Swift package deployment target as `macOS(.v15)`, preventing the package from resolving on older systems.
- **[`scripts/setup_machine.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_machine.sh)**: Contains an explicit runtime check that aborts the setup process if the host version is older than macOS 15.
- **[`README.md`](https://github.com/Lakr233/vphone-cli/blob/main/README.md)**: Lists "macOS 15+ (Sequoia)" as a prerequisite in the platform requirements section.
- **[`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift)**: Documents that the PV=3 profile is incompatible with any macOS version prior to 15.0.

## Verifying Compatibility and Building

Before compiling or running vphone‑cli, confirm your system meets the macOS 15 threshold.

### Check Your Current Version

Run the following command in Terminal:

```bash
sw_vers -productVersion

```

The output must display `15.x` or higher. If you see `14.x` or earlier, the tool cannot function, and the setup script will refuse to continue.

### Build Commands for macOS 15+

With Xcode 15 or later installed, compile the project using:

```bash
make build

```

This invokes the Swift compiler with the macOS 15 deployment target specified in [`Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift). Attempting to build on older macOS versions will fail during package resolution.

### Launching Virtual Machines

Once built, start the virtual iPhone GUI with:

```bash
make boot

```

For headless DFU mode (useful for automated firmware workflows):

```bash
make boot_dfu

```

Both commands query the hardware model in [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift) and will exit immediately if the host does not satisfy the macOS 15 requirement.

## Advanced Features on Newer macOS Versions

While core virtualization works on macOS 15, certain advanced capabilities require newer releases. According to conditional code comments in [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift), the **kernel GDB debug‑stub query** and associated low‑level debugging interfaces are only functional on macOS 26 (Ventura‑plus) and later. These features are gated by runtime version checks and will silently fail or disable themselves on macOS 15 systems.

## Summary

- vphone‑cli strictly requires **macOS 15 (Sequoia)** or later due to Virtualization.framework PV=3 dependencies.
- The **[`Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift)** manifest hardcodes `macOS(.v15)` as the minimum deployment target.
- Setup scripts in **[`scripts/setup_machine.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_machine.sh)** actively block installation on older systems.
- Advanced debugging features may require **macOS 26+**, but core virtualization is fully functional on macOS 15.
- Verify your version with `sw_vers -productVersion` before attempting to build.

## Frequently Asked Questions

### Can I run vphone‑cli on macOS 14 Sonoma?

No. The tool depends on the Virtualization.framework PV=3 profile and private entitlements introduced exclusively in macOS 15. The setup script in [`scripts/setup_machine.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_machine.sh) will explicitly abort if it detects macOS 14 or earlier, and the Swift package manifest in [`Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift) will fail to resolve.

### What specific framework does vphone‑cli use?

vphone‑cli uses Apple’s **Virtualization.framework** with a private entitlement profile. As noted in [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift), the PV=3 hardware model profile requires macOS 15.0 to access the hypervisor instructions and device virtualization features needed for iOS emulation.

### Are there any features that require macOS versions newer than 15?

Yes. According to [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift), the **kernel GDB debug‑stub** functionality and related low‑level debugging queries are only available on macOS 26 (Ventura‑plus) and later. These features are conditionally compiled and will not affect basic VM operation on macOS 15.

### How does the build system enforce the macOS 15 requirement?

The Swift Package Manager manifest in **[`Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift)** declares `platforms: [.macOS(.v15)]`, which causes the dependency resolver to fail immediately on older systems. Additionally, [`scripts/setup_machine.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_machine.sh) performs a runtime version check and exits with an error if the host is running anything older than macOS 15.