How to install very large games with --romfs separate

Why some games will not install

The game's data files, called the RomFS, make up most of an IPA. For Breath of the Wild the project reports 14 of the IPA's 14.7 GB. Tears of the Kingdom's RomFS has about 304,000 files. Leaving the RomFS out keeps a large game under the size iOS extracts, and it makes reinstalls fast: the project reports Animal Crossing's app shrinking from 11 GB to 1.2 GB (PR 368).

Build with --romfs separate

python3 scripts/build_ipa_from_nsp.py ~/Games/MarioWonder -k ~/keys/prod.keys --romfs separate

The IPA is now small. The game files stay on your Mac as one image, <title ID>_build/extract/<version>/RomFS.img, and are reused while the game files do not change, so a rebuild neither packs nor sends them again. This needs the extracted files, so the script rejects --no-keep-extracted together with --romfs separate before it builds.

Install the IPA with your sideloading tool as usual.

Copy the game files to the phone once

At the end the script prints a command like this. Run your printed command, because it holds your phone's ID and your paths:

scripts/push_romfs.sh <device UDID> <bundle ID> "<title ID>_build/extract/<version>/RomFS.img"

• The app must already be installed on the phone. The script copies the image into the app's own folder as Documents/romfs.img.
• The phone must be connected to the Mac. The copy uses xcrun devicectl, which comes with Xcode, and it runs one transfer at a time.
• The command names the app's bundle ID. If your sideloading tool gave the installed app a different one, use the ID of the app that is on the phone.
• If the transfer fails, run it again. The app only uses a complete image, so a copy cut off halfway is never used.

How the app checks the files

A --romfs separate build carries a one-line identity of the image it was built for: the title ID, the game version, the image's size and a hash of its directory tables. At start the app computes the same values from Documents/romfs.img and uses the image only when they match. That check takes milliseconds even for 14 GB.

If the image is missing, cut off or from another game version, the app falls back to a game-files folder if one exists. When no usable files remain, it writes a [RED] line in log.txt with the expected size and the copy command, and shows the same text in an alert. So the alert tells you exactly what to copy.

When to copy the files again

• After a new game version or a new extraction, because the image changed.
• After you delete the app, because deleting an app deletes its Documents folder.

You do not need to copy them after an ordinary rebuild of the same game version.

Copying by hand

You can also copy the image yourself, with Finder or the Files app. The file may keep the name RomFS.img: the app takes Documents/romfs.img in any letter case, and it applies the same checks.