Apple's real iOS 4.2.1 running natively on a Nintendo 3DS.
Not an emulator: the iPod touch 2G's own kernel, SpringBoard and apps run directly on the 3DS's ARM11 CPU.
Install · Controls · What works · Troubleshooting · How it works · Build from source
iOS boots to the home screen in about a minute. Apps open, Safari loads web pages over Wi-Fi, and Cydia comes pre-installed.
| Feature | Notes | |
|---|---|---|
| ✅ | Boot to the home screen, built-in apps | about a minute from power-on |
| ✅ | Touchscreen, HOME, POWER, START/SELECT, L/R | see Controls; slide to unlock and popups over apps work |
| ✅ | Graphics on the 3DS GPU (PICA200) | the iOS interface is drawn by the GPU |
| ✅ | Sound, volume slider | speaker |
| ✅ | Battery level, charging, date and time, brightness | through the 3DS system controller |
| ✅ | Wi-Fi: scan, WPA2, also routers in "WPA2 + WPA3" mode | needs the console's own Wi-Fi firmware, copied automatically by the launcher (or the GodMode9 script); stays connected through the router's key renewals |
| ✅ | Safari | loads pages; big pages can fail with "Cannot allocate memory" (a retry usually works), being worked on |
| ✅ | Cydia | pre-installed |
| ✅ | Screen rotation (accelerometer) | |
| ✅ | D-pad, circle pad | turned 90° to match the upright iOS screen: ← → pages, ↑ ↓ and the stick scroll |
| ✅ | Cameras (Camera.app, back and front, photos) | 320×240 live preview, about 12 fps; photos go to the Camera Roll. No video recording or 3D photos |
| 🧪 | Headphone jack, microphone | iOS switches to headphones when plugged in |
| 🧪 | Gyroscope (CoreMotion) | |
| 🧪 | Modern HTTPS: TLS 1.2/1.3 (TLSFix), current root certificates | Cydia and other unsandboxed apps; not yet Safari, see Limitations |
| 🧪 | Cydia Substrate (tweaks) | pre-installed; installing tweaks no longer hangs the 3DS; tweaks load into SpringBoard and apps, see docs/cydia.md |
| 🧪 | New 3DS: 804 MHz CPU, C-stick, ZL/ZR | L2 cache optional, see docs/n3ds.md |
| ❌ | 3D screen, IR, NFC, video recording | currently unplanned |
✅ works on a real 3DS ·
| Console | Status |
|---|---|
| Old 3DS | ✅ supported, the main test console |
| Old 3DS XL | ✅ boots to the home screen (#7; release 0.3.0 could panic in the accelerometer driver right after boot, fixed in main) |
| Old 2DS | ✅ supported (same hardware as the Old 3DS) |
| New 2DS XL | ✅ boots to the home screen with sound, power button, battery and Wi-Fi (#1, #5) |
| New 3DS, New 3DS XL | untested; expected to behave like the New 2DS XL. On New models ios3ds runs the CPU at 804 MHz; the extra CPU cores and RAM are not used |
All models need Luma3DS (boot9strap). Reports for any model are welcome in the issues.
You need about 15 minutes, a PC and your own copy of the iPod touch firmware. Nothing is installed to the 3DS itself; everything lives on the SD card.
-
A 3DS with Luma3DS (boot9strap) and the Homebrew Launcher, set up the usual way (3ds.hacks.guide).
-
An SD card with about 1.2 GB free.
-
A PC with Python 3.8+ and internet access, needed once to fetch the firmware keys and Cydia:
System Setup Linux sudo apt install python3 python3-cryptographymacOS Python 3, pip3 install cryptography,xcode-select --installWindows use WSL (Ubuntu) and follow the Linux steps; the SD card is /mnt/<letter>
- ios3ds:
ios3ds-<version>.zipfrom the Releases page. Unzip it anywhere. - The iOS firmware (ios3ds can't ship it):
iPod2,1_4.2.1_8C148_Restore.ipsw, the iPod touch 2nd generation on iOS 4.2.1, from Apple's servers via ipsw.me.
Put the SD card in your PC, open a terminal in the unzipped folder and run:
python3 install.py ~/Downloads/iPod2,1_4.2.1_8C148_Restore.ipsw /media/$USER/YOUR_SD_CARDUse your own paths. The card is /Volumes/NAME on macOS and /mnt/e (or another letter) in WSL.
It takes a few minutes and needs about 4 GB of free space on the PC while it works. It:
- decrypts the kernel and the iOS disk from your IPSW, and checks that it is the right file;
- patches the kernel and builds the iOS disk, including Cydia and Cydia Substrate (6.6 MB from apt.saurik.com; add
--no-cydiato skip it) and TLSFix (3.2 MB from GitHub;--no-tlsfixto skip it); - writes three things to the card and touches nothing else:
| On the SD card | What it is |
|---|---|
3ds/ios3ds.3dsx |
the app you start from the Homebrew Launcher |
luma/payloads/ios3ds.firm |
the same, for Luma's chainloader menu |
ios3ds/ |
iOS itself (rootfs.hfs, 1 GB), the patched kernel, and boot.cfg (settings) |
Without an SD card path, the files go to ios3ds-sd/. Copy what is inside that folder to the root of the card.
Open the Homebrew Launcher, start ios3ds and press A. The 3DS reboots into iOS.
Alternatively, hold START while powering on and pick ios3ds in Luma's chainloader menu.
First start:
- The launcher copies your console's Wi-Fi firmware to the card, reading it only. It shows
Wi-Fi firmware: reading NWM .code ..., writes one file,ios3ds/nwm.code, and skips this step afterwards. - The bottom screen shows the version,
SD ok,ARM11 okand a short countdown. Hold B to stop there. - The top screen scrolls a boot log. After about a minute the iOS home screen appears.
- iOS is upright, so turn the 3DS 90° clockwise. The bottom screen shows a copy of iOS that you tap with the stylus.
Wi-Fi: in iOS, open Settings → Wi-Fi and pick your network.
If the launcher showed a red
Wi-Fi fw: ...line, copy the firmware once with GodMode9 instead:
- Hold START while powering on and choose GodMode9.
- Press HOME →
Scripts...→ios3ds-wifi-fw, then confirm with A.Details: docs/wifi.md §3.
| 3DS | iOS |
|---|---|
| Touchscreen | tap, swipe, type |
| HOME or START | Home button |
| POWER (press) or SELECT | lock / sleep |
| L / R | volume down / up |
| Circle pad | scroll (in the direction of the upright iOS screen) |
| D-pad | with the 3DS turned so iOS is upright: ← → previous / next page, ↑ ↓ scroll by about a page |
| X | screen layout: iOS on top + touch copy below → iOS on the bottom only → iOS on top only |
| C-stick (New 3DS) | like the D-pad: flick ← → = previous / next page, ↑ ↓ = scroll by about a page |
| ZL / ZR (New 3DS) | scroll to the top / screenshot |
| POWER (hold ~10 s) | leave iOS: the 3DS switches off; the next power-on is your normal Luma + HOME Menu |
| SELECT + START (hold) | debugging only: crash iOS on purpose and write a report to the log |
ios3ds never writes to the 3DS's internal memory (NAND) or firmware. It has no code that could. It only reads and writes files on the SD card.
A homebrew app can't start another system directly, so the launcher swaps files on the SD card and reboots:
- It creates
ios3ds/swap.flg, a "swap in progress" note. - It renames your
boot.firm(Luma) toios3ds/luma.firm. - It renames
ios3ds/ios3ds.firmtoboot.firm. - It reboots.
The first thing ios3ds does is undo this, so Luma is back as boot.firm before iOS even starts. These are renames, never copies, so a power cut can't leave a half-written boot.firm. If it ever stops halfway:
- the 3DS falls back to the backup
boot.firmin its internal storage (set up by the 3ds.hacks.guide); - the launcher offers Y: restore Luma when it finds a leftover
ios3ds/luma.firm; - or rename
ios3ds/luma.firmback toboot.firmon a PC.
As with any homebrew, back up your SD card first. More: docs/real-hardware.md.
-
Logs: every boot writes
sd:/ios3ds/log.txt, and the previous one is kept aslog_prev.txt. Please open an issue and attachlog.txt. -
Settings: they live in
sd:/ios3ds/boot.cfg, a text file. Useful switches:Switch Effect gpu=0don't use the 3DS GPU at all: try this first if the screen stays black or garbled ca_gpu=0draw the iOS interface in software (slower) screen=0/1/2start in screen layout top / both / bottom camera=0,gyro=0,hp_route=0turn off the cameras, the gyroscope, or headphone switching diag=1extra diagnostics in the log -
Re-running the installer replaces
boot.cfg; the old one is kept asboot.cfg.old. The installer refuses a card with a leftoverios3ds/luma.firm: start ios3ds once, or restore Luma first. -
Uninstall: delete
ios3ds/,3ds/ios3ds.3dsxandluma/payloads/ios3ds.firmfrom the card.
- iOS 4.2.1 is the newest possible: later versions need an ARMv7 CPU, and the 3DS's ARM11 is ARMv6.
- HTTPS: iOS 4.2.1 itself speaks TLS 1.0 at most. The pre-installed TLSFix tweak adds TLS 1.2/1.3 and EC certificates for apps that use iOS's networking (Cydia, ...), and current root certificates are added (docs/certificates.md); leave it out with
--no-tlsfix. Safari and App Store apps run in Apple's sandbox, which keeps Cydia Substrate (and so TLSFix) out, so by default they still speak TLS 1.0 only (GitHub, Wikipedia, apple.com, … don't open there). A kernel patch can relax the sandbox (make sd SANDBOX=1), but then Safari runs out of memory loading TLSFix on the 128 MB device, so it is off by default (docs/cydia.md). Sites with expired or untrusted certificates are refused everywhere. - OpenGL ES apps and games: 3D runs through our own OpenGL ES 1.1 engine. There is no ES 2.0 and no PVRTC textures.
- Tweaks (Cydia Substrate): Substrate is pre-installed and held at its version; don't remove or "upgrade" it in Cydia. Tweaks load into SpringBoard and apps, not into system daemons (injecting into launchd hangs iOS 4.2.1 on the 3DS, so ios3ds blocks it and repairs
/etc/launchd.confat boot). - Memory: iOS gets the iPod's 128 MB. Big pages can fail in Safari with "Cannot allocate memory" (a retry usually works); this is being worked on. New 3DS models' extra RAM and CPU cores are not used yet.
- Cameras: 320×240 preview at about 12 fps (photos are scaled up from it); no video recording and no 3D photos.
- No hardware for: Bluetooth (the 3DS has none), the 3D screen, IR, NFC.
- Updates reset iOS: installing a new version rebuilds the iOS disk, so settings, saved Wi-Fi networks and installed Cydia packages start fresh.
- Leaving iOS means holding POWER (a hard power-off); there is no clean shutdown back to the 3DS yet.
- Not supported: activation, iTunes sync and the data-protection keybag are stubbed out.
3DS boot (Luma3DS chainloader)
├─ ARM9 our "monitor": both screens' consoles, SD card, the iOS root disk (served from rootfs.hfs),
│ Wi-Fi (AR6014 driver + WPA2), system controller, cameras, gyro, screen copy
└─ ARM11 Apple's XNU kernel, stock, + binary patches (kernel/patches.json) + our "shim"
├─ timers, interrupts, console → mapped onto the 3DS's MPCore
├─ display → Apple's own LCD driver on a fake register page; the PICA200 GPU copies to the LCDs
├─ audio, touch, buttons, battery, Wi-Fi … → mailboxes to the ARM9
└─ launchd → configd, mediaserverd, … → SpringBoard → your apps
Apple's kernel believes it is running on an iPod touch. Where the 3DS hardware differs, small patches and the shim translate. The ARM9 handles everything slow or Nintendo-specific. Full picture: docs/architecture.md.
The project has its own QEMU machine (-M nintendo3ds, docs/emulator.md) that models the 3DS hardware, from the GPU to Wi-Fi, cameras and gyro. Every change is tested there before it reaches a console. Citra/Azahar only emulate 3DS apps; they can run the launcher but not ios3ds itself.
Linux. Requirements: Python 3 with cryptography, an arm-none-eabi toolchain (Arm GNU Toolchain or devkitARM), mtools, dosfstools, sfdisk, git. The iOS toolchain builds ldid, which needs OpenSSL 3 headers; on systems with OpenSSL 4 also install OpenSSL 3 (the script finds /usr/include/openssl-3 and similar).
make toolchain # check the tools
make fwprep IPSW=~/iPod2,1_4.2.1_8C148_Restore.ipsw # decrypt kernel, device tree, rootfs -> build/staging
scripts/build-hfsplus.sh # HFS+ image editor (xpwn)
scripts/build-ios-toolchain.sh # armv6 iOS toolchain for our iOS programs (once)
make userland # our iOS programs -> build/rootfs-add/
make sd # SD card tree -> build/sd/ (copy its contents to the card)
make test # offline unit testsOptional:
make qemubuilds the emulator, about 10 minutes.make emubootsbuild/sd.imgin it.make launcherbuildsios3ds.3dsxand needs devkitARM + libctru.make releasebuilds the release zip (docs/release.md).
No Apple files in this repository. You supply the IPSW, and everything Apple-derived is generated into build/ (gitignored). The patch recipes hold only addresses and the few original bytes needed to check that the right firmware is being patched.
| architecture.md | boot chain, memory map, every hardware bridge |
| real-hardware.md | testing safely on a console |
| emulator.md | the QEMU nintendo3ds machine, Azahar |
| gpu.md · pica200.md | OpenGL ES engine, CoreAnimation and the screen copy on the PICA200 |
| audio.md | speaker, headphones, microphone |
| mcu.md | battery, clock, buttons, sliders, accelerometer, gyroscope |
| wifi.md · certificates.md | Wi-Fi driver, WPA2, iOS integration; HTTPS roots |
| camera.md | cameras in Camera.app |
| input-design.md | touch, buttons, circle pad |
| cydia.md | the pre-installed Cydia |
| re-log.md | the reverse-engineering log, step by step |
| hwlogs/ | logs from real hardware runs |
- samhenrigold/qemu-ios (Light Touch): research on booting 8C148, invaluable.
- devos50/qemu-ios: iPod touch emulation and S5L8720 notes.
- darwin-on-arm (winocm): boot_args and pexpert reference.
- libn3ds, Luma3DS, linux-3ds, dsiwifi, GBATEK and 3dbrew: 3DS hardware references.
- Normmatt's SD driver, FatFs by ChaN, xpwn, and The Apple Wiki.
- Everyone testing on real consoles in the issues.
GPL-3.0-or-later (LICENSE), with these exceptions:
boot/arm9/sdmmc.candemu/qemu/are GPL-2.0-or-later.boot/arm9/fatfs/is under FatFs's 1-clause BSD licence.boot/common/font8x8_basic.his public domain.
Downloaded during install, never shipped in the release zip: Cydia and its base packages and Cydia Substrate (Jay Freeman, from apt.saurik.com), and TLSFix 1.3 (ObscureMosquito/TLSFix, fork of nfzerox/TLSFix; it contains OpenSSL 1.1.1w, under the OpenSSL and SSLeay licences), under this licence:
MIT License
Copyright (c) 2026 nfzerox
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE 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. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
iOS, iPod and XNU are trademarks of Apple; Nintendo 3DS is a trademark of Nintendo. This is an independent research project, not affiliated with either.