Download and install nxnative

Check the requirements

Install the tools on your Mac (once)

Install Xcode 27.1 first, from Apple's download page, not the App Store. The shaders are built with its Metal compiler and the App Store may offer a newer Xcode. If a newer Xcode is installed too, rename 27.1 to Xcode-27.1.app and run sudo xcode-select -s /Applications/Xcode-27.1.app. Then open Terminal and run these commands. The third line clones the repository, so you can skip the zip if you prefer git.

xcodebuild -downloadComponent MetalToolchain
git clone https://github.com/seedds/nxnative.git && cd nxnative
brew install xcodegen zstd glslang
brew install --cask dotnet-sdk
python3 -m pip install lz4 "capstone>=5,<6" fonttools nsz zbic "backports.zstd; python_version < '3.14'"

Put your game in a folder

Put the game, plus its update and DLC if you have them, in one folder. The script reads the title ID from the package and falls back to the [title ID] in the file name. Look up your title ID on the games page to check that your game is supported.

~/Games/MarioWonder/
  Super Mario Bros. Wonder [010015100B514000][v0].nsp
  Super Mario Bros. Wonder [010015100B514800][v327680].nsp

Build the IPA

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

The IPA appears in the game's folder. Be patient: the first build takes 30 to 60 minutes, and building again is much faster. Useful options:

• --platform mac-app builds a Mac app instead, to open from Finder.
• -l ja or -l French sets the game language.
• --romfs separate makes a smaller IPA for very large games. The script prints a command that copies the game files to your phone once.
• -p v0 packs an older version. The folder still needs both NSPs.
• --no-keep-extracted deletes the extracted game files after the build. They are kept by default.
• --work-dir puts the build folder on another drive.

Install the IPA on your iPhone or iPad

The IPA is unsigned, so a sideloading tool signs and installs it. The project names three tools:

1. Pick a tool: AltStore, Sideloadly or LiveContainer, and set it up with its own instructions.
2. Move the IPA to the device or open it in the tool, then install it.
3. If the tool offers Increased Memory Limit, turn it on. The bigger games need it.
4. If the game is too big to install, rebuild with --romfs separate and run the command the script prints.

Details and tips are in the sideloading guide.

Open the app and play

1. Open the app. A settings screen appears. Review it, or leave the tested defaults as they are.
2. Tap Play. The first time a scene appears you may see a "Preparing shaders" bar and short stutters. This is normal and happens once per scene.
3. Use the touch controls (tap 2D or 3D at the top to change the layout) or connect a game controller.
4. Your saves are in the Files app under the game's name, in save/.