Wii setup guide

Prefer an AI to walk you through it?

Copies a ready-made prompt with all the context + the steps below onto your clipboard — paste it into ChatGPT or Claude and it'll guide you through the whole setup, one step at a time, for your Wii. You don't need to read it.

📋 Copy this guide as an AI prompt

Where are my games? (reading the Library's Location badge)

A game's files can exist in up to three separate places, and the Library's badge tells you which — it does not mean "everywhere":

• On Wii ✓ / Not on Wii yet — whether it's been pushed to the Wii itself over WiFi FTP. This is the normal state for a game you've added and synced the usual way.
• Pi only — kept on the Pi (in archive/) but deliberately removed from the Wii (via "Remove from Wii, keep on Pi"). Not on the USB drive either unless you separately copied it.
• Wii only — the Pi copy was removed ("Remove from Pi, keep on Wii"); only the Wii has it now. The row is kept so you can still track/delete it later.
• 💿 Drive only — imported FROM the USB drive plugged into the Pi (via Sync → Import drive games). Its files live only on that USB drive, not staged on the Pi at all, until you hit 💾 Copy to Pi on it. Marked clearly since it's the one state where unplugging the drive means the game is temporarily unreachable — these rows only appear in the Library while that drive is actually connected, and disappear (not deleted, just hidden) when it's not. If you swap in a different drive, any that turn out to be genuinely gone (not just unplugged) are cleaned up automatically.

A game staged on the Pi (the default, "active" case) can ALSO be copied onto the USB drive by hand with 📀 Copy to drive — that's a separate, manual action from Wii-syncing. Once it is, its badge shows a "+ on drive" tag alongside the Wii state, and the button switches to 🗑️ Remove from drive so you can pull it back off without touching the Pi copy or Wii sync state.

1. What you need

• A Wii (any model, including the Wii Mini's SD-only limits aside — a full Wii with USB is assumed).
• An SD card (2–32 GB, FAT32) for installing homebrew.
• A USB hard drive or flash drive for the games, formatted FAT32 (see below).
• The Wii and this server on the same LAN.

2. Install the Homebrew Channel

The Homebrew Channel is the launcher that runs everything else. The easiest, up-to-date method is the “Let's Go Gambling / str2hax / LetterBomb” style exploit guide at wii.hacks.guide — follow it end to end. When done you'll have the Homebrew Channel installed.

Download / reference: https://hbc.hackmii.com/

3. Install cIOS (d2x) — required for USB drives

This is the piece everything USB depends on. A stock Wii can't read a USB hard drive at all — not USB Loader GX, not an FTP server, nothing. A cIOS (custom IOS, the d2x build) adds USB-HDD support. Install it once, up front.

• Get the d2x cIOS Installer from the official guide: wii.guide/cios (or search “cios” / “d2x” in SD card items). Upload its zip in SD card items and the apps/d2x-cios-installer/ folder is placed on the SD for you.
• The Wii must be online when you run it — the installer downloads the base IOS from Nintendo's servers.
• On the Wii: Homebrew Channel → d2x cIOS Installer → install slot 249, base 58 (a second slot 250, base 56 makes a good backup). Defaults otherwise.

Skip this and the USB drive simply never appears — you'll only ever see the SD card over FTP.

4. Install USB Loader GX and Nintendont

These are the apps that actually launch games from the USB drive — USB Loader GX for Wii games, Nintendont for GameCube games. Put each app's folder in SD:/apps/<appname>/, then launch it from the Homebrew Channel.

• USB Loader GX — Open Shop Channel · GitHub
• Nintendont — Open Shop Channel · GitHub

USB Loader GX can install a channel and launch Nintendont for you, so you mainly interact with USB Loader GX.

5. Install an FTP server — use WiiXplorer

This app pushes games to the Wii over FTP; the FTP server just has to expose the USB drive. Use WiiXplorer — it mounts SD and USB through the cIOS from step 3, has a built-in FTP server, and a proper Wiimote-pointer UI.

• WiiXplorer — Open Shop Channel (or search it in SD card items and Sync it to the SD).
• Launch it from the Homebrew Channel, then start its FTP server (Network menu). It shows the Wii's IP and listens on port 21.

Avoid the old FTPii (0.0.22). It only mounts the SD card and small flash drives — it cannot mount a USB hard drive, and its Wiimote support is minimal. Fine if you only sync to the SD, but for USB games use WiiXplorer.

6. Format the USB drive and pick the right port

• Format the USB drive as FAT32 (not exFAT/NTFS). USB Loader GX and Nintendont read FAT32 most reliably. Large drives can still be a single FAT32 partition with the right tool.
• Plug the drive into the Wii's bottom USB port — the one nearest the stand. That port is the reliable one for USB Loader GX; the top port often isn't detected.
• This app already lays the files out exactly how the Wii expects: /wbfs/<Title> [ID6]/ for Wii games and /games/<Title> [ID6]/ for GameCube. You don't arrange anything by hand.

7. Find the Wii's IP address

• Easiest: start WiiXplorer's FTP server — it shows the Wii's IP right on the TV, e.g. 192.168.1.50, along with the port (21).
• Or on the Wii: Wii Settings → Internet → Connection Settings → (your connection) → Test Connection shows the assigned IP.
• Tip: give the Wii a DHCP reservation in your router so its IP never changes.

8. Point this app at the Wii

Open the Sync page and enter the Wii's IP from step 7 (e.g. 192.168.1.50) — it saves instantly, no restart, and the Wii can be powered off when you set it. Also set the FTP root there, usually /usb.

The FTP server exposes each device as a top-level folder, so staged wbfs/ and games/ land at /usb/wbfs and /usb/games. (You can also preset WII_IP/FTPII_ROOT as container env vars — they're just the initial defaults.)

9. Start the FTP server and let it sync

• On the Wii, launch WiiXplorer and start its FTP server. Leave it running.
• This app polls for the FTP server every 20 seconds. Within one poll it detects the Wii and starts transferring every staged game that isn't synced yet.
• Watch progress on the Sync page. It's slow and runs in the background — a 1 GB game can take 15–40 minutes. You can close the browser; the server keeps going.
• When a game finishes it's marked synced in the Library and the file is kept on the server (your archive). Deleting from the Library is a separate, explicit action.

Faster: copy over USB plugged into the Pi (recommended)

The Wii's WiFi FTP is slow (~0.5–1.5 MB/s) and can drop on big transfers. For the initial bulk load especially, it's far faster to plug the Wii's USB drive into the Pi, let the app copy games straight to it at full USB speed, then move the drive back to the Wii.

It's a one-time host setup that persists across reboots:

1. Plug the drive into the Pi and find its UUID: lsblk -f.
2. Pin it in /etc/fstab so only that drive mounts there, owned by the container user (uid 1000) and writable — the uid/umask are required or the app can't write:
   UUID=XXXX /mnt/wii-usb vfat defaults,uid=1000,gid=1000,umask=000,nofail 0 0
   then sudo systemctl daemon-reload && sudo mount /mnt/wii-usb.
3. Bind-mount it into the container: add - /mnt/wii-usb:/wii-usb under the wii-sync service's volumes:, then recreate the stack (mount the drive first, or the bind captures an empty folder).
4. On the Sync page set USB drive path to /wii-usb (or pick it from the dropdown), then Sync to USB. Move the drive back to the Wii when done.
5. Optional but recommended: a fstab entry only mounts at boot or on an explicit mount command — plugging the drive in later won't mount it on its own. Add a udev rule so it auto-mounts the instant you plug it in (see below).

vfat can't change ownership on a remount — if you mounted it wrong first, unmount and mount fresh: docker stop wii-sync; sudo umount /mnt/wii-usb; sudo mount /mnt/wii-usb; docker start wii-sync.

📋 Copy setup prompt for an AI assistant

That copies a ready-made prompt (all the context + exact steps) to your clipboard — paste it into ChatGPT or Claude and it'll walk you through the setup for your specific drive. You don't need to read it.

Automatic USB mount/unmount (recommended)

Why this matters: a drive left mounted while idle is at real risk of directory-table corruption if it's ever unplugged without unmounting first — this has actually happened. With this set up, the app mounts the drive only while it's doing something (syncing, browsing, copying, patching) and unmounts the instant it's done, so it's essentially always safe to unplug.

1. On the Pi, from a checkout of the app's repo: sudo ./deploy/setup-usb-bridge.sh — this installs a tiny root-owned control script, generates a dedicated SSH keypair, and restricts that key (via a forced command= in authorized_keys) so it can only run mount/unmount — nothing else, even with the key in hand.
2. Move the generated wii_usb_ssh_key next to your compose.yaml, then add under the wii-sync service:
   environment:
  WII_USB_SSH_HOST: root@<the Pi's own LAN IP>
volumes:
  - ./wii_usb_ssh_key:/run/secrets/wii_usb_ssh_key:ro
3. Recreate the stack. The header banner then shows live "USB drive mounted — DO NOT unplug" / "unmounted — safe to unplug" on every page.

Full walkthrough with troubleshooting: see DEPLOY.md → "Automatic USB mount/unmount" in the repo. Skip this entirely and every USB feature still works — it just requires the drive to already be mounted (sudo mount /mnt/wii-usb) before you use it.

📋 Copy setup prompt for an AI assistant

Replacing or adding a USB drive

Swapping in a new/replacement drive (e.g. after a failed one) — same steps as the very first setup, pointed at the new drive:

1. Format the new drive FAT32. Plug it into the Pi, find its UUID: lsblk -f.
2. Update the /etc/fstab line from the first-time setup above to the new UUID (same mountpoint, same uid=1000,gid=1000,umask=000,nofail options), then sudo systemctl daemon-reload && sudo mount /mnt/wii-usb.
3. If you're using the automatic mount/unmount bridge (below), re-run sudo ./deploy/setup-usb-bridge.sh — it's safe to re-run and picks up the new drive automatically (the control script always targets the fstab mountpoint, not a specific UUID itself).
4. On the Library page, use 📀 Copy to drive (per-game, or select several and Copy selected to drive) to hand-pick which games go on first — this only copies files, your Pi library and sync state are untouched.
5. Once the drive has a games/ or wbfs/ folder on it (the copy above creates one), turn on "Auto-sync & import when this drive is connected" on the Sync page — future reconnects then sync/import automatically. It deliberately won't auto-fire on a completely blank drive with neither folder yet, as a safety check against writing to the wrong device.

📋 Copy setup prompt for an AI assistant

ISO patches (optional)

• Hit 🩹 Patch ISO on a game in the Library to apply an .xdelta patch (from tools like Multipatcher/xdelta3) — e.g. UnclePunch Training Mode for Melee. This builds a new, separate game with its own ID; the original is untouched, so you keep both. Works on games staged on the Pi and on games marked 💿 Drive only (imported from the USB) — the latter reads the source straight off the drive, so it must be plugged in. Only offered on games that aren't themselves already a patched copy.
• Applying runs in the background — watch the Jobs list for progress on a multi-GB ISO. A drive-sourced game takes a bit longer (reading the ISO off USB first).
• Give it a custom name in the modal — most patches don't show their own name in-game, so this is what tells it apart from the original in USB Loader GX / Nintendont.
• The patch must be built against the exact same source ISO (region/revision) as the game you're patching, or xdelta3 will fail to apply it (or it applies incorrectly).

Riivolution mods (optional)

Riivolution mods (Project+, texture packs, romhacks distributed as a riivolution/*.xml + content folder) normally patch a game at boot, from files on SD/USB — that's what USB Loader GX's own Riivolution screen reads. This app offers two ways to use one:

• Runtime pack (original method): add the pack in the Riivolution packs section at the bottom of the Library page. It syncs into the shared riivolution/ folder on the drive/SD; pick it in USB Loader GX's per-game Riivolution setting at launch. Needs no baking, but only works with loaders that actually support Riivolution-from-USB (older USB Loader GX builds only scanned the SD card — check Settings → About if the option doesn't appear).
• 🩹 Patch ISO (Riivolution) — bake into a standalone game: once a pack is attached (via the section above), this button builds a new, separate library entry with the mod's files and memory/code patches already applied — no runtime Riivolution needed, works like any normal game. Uses riivultimatum, an actively-developed but still early tool — as of this writing it's verified in the Dolphin emulator but not yet proven on real hardware by its author. It reports each patch as applied/skipped/failed and refuses to build a broken image, but treat the very first mod you bake as a real-hardware test: keep the original game (untouched either way) and report back if it doesn't boot.

Cover art (optional)

GameTDB's automatic cover lookup (used across the app) is keyed by Game ID, so a baked patch-ISO copy (its ID is invented locally — see above) can never have one automatically. Hit 🖼️ Cover on a game in the Library to upload and crop one by hand — works on any game, not just patched copies.

• The crop box is fixed to 160×224, USB Loader GX's own default 2D-cover size (same proportions GameTDB uses) — drag to reposition, use the slider to zoom, and it always comes out the right shape.
• Saved as apps/usbloader_gx/images/2D/<Game ID>.png in staging — USB Loader GX's own default cover folder — so it syncs like any other file: automatically over FTP, and via the local-USB extras copy / per-game 📀 Copy to drive.
• If your loader is configured with a different cover folder (Settings → Paths in USB Loader GX), you'll need to point it back at the default, or copy the file over by hand.

Cheat codes (optional)

• Tick “Fetch cheat codes” when you add a game, or hit Cheats on a staged game in the Library. This downloads community Gecko/Ocarina codes for that game's ID and stages them, so they sync to the Wii with the game.
• Turn cheats on in the loader: in USB Loader GX open the game's settings → Game Load → Ocarina (cheats) On, then pick codes. For GameCube, enable Cheats in Nintendont's settings.
• Cheat files land in a txtcodes/ folder on the drive. If the loader doesn't see them, point its txt cheat path at the USB drive (this is a known per-loader setting to verify).
• Codes are community-made and free — separate from the game. This app never provides game files.

Auto-boot into USB Loader GX or the Homebrew Channel (optional)

To skip the System Menu and land straight in a loader on power-on, use Priiloader (a small tool you install alongside the Homebrew Channel — see the guide in step 2). This is a one-time Wii-side setup; wii-sync only syncs game files, it doesn't install loaders or homebrew.

• Enter Priiloader: power the Wii on while holding RESET.
• Open Settings → Autoboot and choose one:
  • Homebrew Channel — boots straight to HBC, where you pick USB Loader GX / Nintendont.
  • Installed File — boots a specific app; point it at a USB Loader GX forwarder (a tiny boot.dol) to go directly into the loader.
• Keep a way back: set “Return to” to the System Menu so holding RESET still reaches Priiloader.

Priiloader + forwarders: wii.hacks.guide/priiloader.

Online play with Wiimmfi (optional)

Nintendo's original online servers are shut down; Wiimmfi is the community replacement that revives online for supported games (Mario Kart Wii, Brawl, etc.). Nothing extra to sync — USB Loader GX patches the game on launch, so it's a loader setting, not a file.

• Let this app set it globally: flip “Auto-configure USB Loader GX for Wiimmfi” on the Sync page. It writes the loader's GXGlobal.cfg to the SD and turns on SD sync, so every game defaults to Wiimmfi after the next sync. (Verify it once on the Wii — the config key can differ by loader build.)
• Or per game, in USB Loader GX: open the game's settings → Private Server → Wiimmfi.
• Launch the game and connect as normal — it now talks to Wiimmfi instead of the dead servers.

More: wiimmfi.de. Riivolution mods like Project+ run their own online, so you don't need this for those.

Then: play

Move the USB drive back to the Wii's bottom port (if you unplugged it), launch USB Loader GX for Wii games or Nintendont for GameCube games, and your transferred titles appear in the list.