iEmu

iEmu is a fork of QEMU adding emulation of Apple ARM SoCs, derived from the ChefKiss Inferno project.

Project status, boot-pipeline progress, and open threads live in docs/STATUS.md.

Current status: iOS 18.5 (iPhone 11) boots to userspace on the emulated t8030. We are close to a full boot (working through late-boot memory corruption); once 18.5 boots cleanly the next target is iOS 26.

Building

See docs/BUILD.md for full build and install instructions (macOS Apple Silicon and Linux), including the required --enable-nettle backend and the util/mlib submodule. In short, on macOS:

brew install glib pixman pkg-config ninja meson nettle gmp gnutls lzfse
git submodule update --init util/mlib
./configure --target-list=aarch64-softmmu --enable-lzfse --enable-nettle \
  --extra-cflags="-I/opt/homebrew/include -I/opt/homebrew/opt/lzfse/include" \
  --extra-ldflags="-L/opt/homebrew/lib -L/opt/homebrew/opt/lzfse/lib"
ninja -C build qemu-system-aarch64

On Linux (Debian/Ubuntu); see docs/BUILD.md for Fedora and the lzfse-from-source fallback:

sudo apt install build-essential ninja-build meson pkg-config \
  libglib2.0-dev libpixman-1-dev nettle-dev libgmp-dev \
  libgnutls28-dev liblzfse-dev libslirp-dev \
  libgtk-3-dev libsdl2-dev libegl-dev libgbm-dev libepoxy-dev
git submodule update --init util/mlib
./configure --target-list=aarch64-softmmu,x86_64-softmmu \
  --enable-lzfse --enable-nettle --enable-slirp \
  --enable-gtk --enable-sdl --enable-opengl \
  -Dwerror=false
ninja -C build qemu-system-aarch64 qemu-system-x86_64

Both qemu-system-aarch64 (the iOS guest) and qemu-system-x86_64 (the USB bridge companion VM) must be built on Linux. --enable-slirp and libslirp-dev are required because the companion VM uses user-mode networking. The --enable-gtk/--enable-sdl flags and their -dev libraries give you a GUI window (see Display / UI below); omit them for a headless-only build.

Note for GCC 13+: -Dwerror=false is required. The codebase was developed on Apple clang, which is more permissive than GCC 13+; the flag disables warnings-as-errors without affecting correctness.

The t8030 machine runs under TCG, so the iOS boot needs no host hypervisor and works the same on Linux, Windows, and macOS.

Running

Quick start (Linux)

setup.sh is the recommended way to get from a fresh Ubuntu 24.04 install to a booted iOS 18.5 system. It handles all steps end-to-end: installing dependencies, building both QEMU targets, downloading and extracting the IPSW, creating disk images, patching the restore ramdisk, building the companion VM, running the restore, and booting the result.

./setup.sh          # run all steps (idempotent — safe to re-run)
./setup.sh boot     # boot only (after a completed restore)
./setup.sh --help   # list individual steps

Individual steps can be run in isolation (e.g. ./setup.sh deps build) and each step is skipped automatically if it has already completed. See docs/FIRMWARE.md for what each step does and for manual / advanced instructions.

Display / UI

iEmu opens a GUI window when built with a display backend and run on a machine with a display server. The window is split: the emulated iOS screen on the left and a live boot-log panel on the right (rendered by apple_displaypipe_v4). setup.sh auto-detects this — it uses gtk on Linux when $DISPLAY/$WAYLAND_DISPLAY is set, cocoa on macOS, and falls back to none (headless) otherwise. Override with IEMU_DISPLAY=none|gtk|sdl|cocoa.

• Linux: -display gtk (or sdl) — requires the GTK/SDL build flags above and an X11/Wayland session.
• macOS: -display cocoa.
• Headless / over SSH: -display none, then watch the serial log.
• Serial output (boot log): tail -f /tmp/iemu.log
• QEMU monitor (memory inspection, screenshots): nc -U /tmp/iemu-mon.sock — screendump out.ppm captures the current frame even when headless.

What renders today: the boot-log panel is live from the first frame. The left (iOS) panel shows a diagnostic color-stripe test pattern while VRAM is empty, then whatever iOS draws to the framebuffer. Full iOS UI (SpringBoard) does not render yet — the installed-OS boot currently stalls at the SEP/AES keystore before drawing UI (see docs/STATUS.md); this is the active frontier.

Warning: Do not use x/i in the QEMU monitor — the disassembly hook is unimplemented on this target and will abort the process immediately. Use x/gx <addr> for memory reads and info registers -a for CPU state.

Manual invocation

The binary is build/qemu-system-aarch64. Verify it built correctly:

build/qemu-system-aarch64 -machine help | grep -E 't8030|s8000'
# expected: t8030  Apple T8030 SoC (iPhone 11)
#           s8000  Apple S8000 SoC (iPhone 6s Plus)

A full boot requires an extracted iOS firmware set (kernelcache, device tree, trustcache, AP ticket, SEP ROM + firmware) and a set of NVMe disk images — none of these are included in this repo. With those assets in place the core invocation is (set FW and D to your firmware/disk directories):

build/qemu-system-aarch64 \
  -M t8030,trustcache=$FW/trustcache,ticket=$FW/ticket.der,boot-mode=exit_recovery,kaslr-off=true \
  -kernel $FW/kernelcache -dtb $FW/DeviceTree.im4p \
  -append "serial=3 wdt=-1 launchd_unsecure_cache=1 -v" \
  -smp 6 -m 4G \
  -display gtk -serial file:/tmp/iemu.log \
  -drive file=$D/root,format=raw,if=none,id=root \
    -device nvme-ns,drive=root,bus=nvme-bus.0,nsid=1,nstype=1,logical_block_size=4096,physical_block_size=4096

See docs/FIRMWARE.md for step-by-step instructions on downloading the IPSW, extracting firmware files, creating disk images, and running the restore. See docs/RUNNING.md for the complete invocation reference including all NVMe namespaces and the real-SEP boot variant. Current boot pipeline status is in docs/STATUS.md.

Legal Disclaimers

iEmu is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement.

By using this software, you acknowledge that you are solely responsible for how you use it. The iEmu project is not responsible for any damage, legal issues, data loss, or other consequences arising from its use.

This project is intended for lawful purposes only. Users are responsible for complying with all applicable laws, licenses, and agreements, including copyright, trademark, and End User License Agreements (EULAs).

The iEmu project does not condone or support piracy, copyright infringement, or any illegal activity.

iEmu is a derivative of the QEMU project (GPLv2-or-later) and of the ChefKiss Inferno project. New code added in iEmu is licensed under the GNU Affero General Public License, version 3, except where individual files declare otherwise. Files inherited from ChefKiss Inferno retain their original AGPLv3 license. See LICENSE for the combined notice.

Full license texts: COPYING (QEMU, GPLv2), COPYING_GPL-3.0 (GPLv3), COPYING_AGPL-3.0 (AGPLv3), and COPYING.LIB (LGPL).

The parts of QEMU which are licensed under the "version 2 or later" clause retain their original license restrictions and copyright holders.

Network Use / Source Availability (AGPLv3 §13)

iEmu contains AGPLv3-licensed code. Under Section 13 of the AGPLv3, if you run a modified version of iEmu and let users interact with it remotely over a network (for example as part of a hosted or "SaaS" service), you must prominently offer those users the opportunity to receive the Complete Corresponding Source of the version you operate, at no charge, from a network server. That source must include your modifications; a link to an upstream project alone is not sufficient.

The canonical public source for iEmu is published at https://github.com/cryphorix/iEmu. Operators of a network service built on iEmu should additionally surface a "Source" link (e.g. in an About/Settings screen or API endpoint) pointing to the corresponding source of their deployed version.

QEMU is a copyright and trademark of Fabrice Bellard. QEMU is unaffiliated with this project.

iOS is a copyright and trademark of Apple, Inc. Apple, Inc. is unaffiliated with this project.