How to Install Dusk on macOS (Twilight Princess PC Port Guide)

Install Dusk on macOS — Apple Silicon and Intel Mac. Verified file paths, real settings menus, Gatekeeper workaround, and v1.0.0 launch crash workarounds.

Published 2026-05-10

Dusk ships separate native builds for Apple Silicon (M-series) and Intel Macs. This guide covers both, plus the v1.0.0 launch issues that some Apple Silicon users have reported.

Time required: ~10 minutes Difficulty: Easy (with caveat — see Known Issues below)

⚠️ Read This First (Apple Silicon Users)

There are open GitHub issues at v1.0.0 about Dusk crashing on launch on Apple Silicon Macs:

These are not universal — many M-series users report Dusk runs fine. But if you hit a “Dusk quit unexpectedly” dialog on first launch, you’re not alone. Check the linked issues for the latest workarounds.

There is also #830 — Can’t bind keyboard MacOs (open). Keyboard binding through the Dusk UI is not currently working on macOS; use a controller until this is patched.

Before You Start

1. Identify your Mac’s architecture

Apple menu → About This Mac
“Chip” line will say one of:
- Apple M1 / M2 / M3 / M4 / Pro / Max / Ultra → Apple Silicon, use the arm64 build
- Intel Core … → Intel Mac, use the x86_64 build

2. Your own GameCube Twilight Princess disc dump

Required. Dusk does not include game files. See How to legally dump your TP disc.

Supported at v1.0.0:

GameCube USA (GZ2E01) — SHA-1 75edd3ddff41f125d1b4ce1a40378f1b565519e7
GameCube PAL (GZ2P01) — SHA-1 2601822a488eeb86fb89db16ca8f29c2c953e1ca

3. macOS version

Per the source code, Dusk targets recent macOS via the Metal graphics backend. The minimum macOS version isn’t officially documented, but macOS 12 (Monterey) or newer is a reasonable working assumption. Building from source requires Xcode 16.4+ (per docs/building.md) — but you don’t need this just to run the prebuilt binary.

Step 1 — Download Dusk

Go to github.com/TwilitRealm/dusk/releases
Under v1.0.0 Assets, pick the file matching your Mac:

Mac	File	Size	SHA-256
Apple Silicon	`Dusk-v1.0.0-macos-arm64.zip`	28 MB	`5ad0b10ada553b33ea3aa11949ca9cdf1ab4b085cce28dd4547bc152b459c9ce`
Intel	`Dusk-v1.0.0-macos-x86_64.zip`	30 MB	`e2250f963e6de1aa41e2efcf5d915f8fb207719bdfe39517714155cf25ff16b7`

Verify the download in Terminal:

shasum -a 256 ~/Downloads/Dusk-v1.0.0-macos-arm64.zip

⚠️ If you accidentally download the wrong arch, Dusk either won’t launch or will run via Rosetta 2 with a performance hit. Pick the matching arch.

Step 2 — Extract and Move

Double-click the .zip in Finder. It expands to a Dusk.app bundle.
Drag Dusk.app to Applications (or any folder you prefer).

⚠️ Avoid placing it inside a folder synced by iCloud Drive or Dropbox — file sync conflicts can corrupt save files.

Step 3 — First Launch (Gatekeeper Workaround)

Dusk v1.0.0 is not notarized by Apple. The first time you run it, macOS Gatekeeper will block it.

macOS 12–14 path

Open Applications in Finder
Right-click Dusk.app → Open
A dialog appears: “macOS cannot verify the developer of ‘Dusk’. Are you sure you want to open it?”
Click Open

This whitelists Dusk going forward; you can launch normally after this.

macOS 15 path

On Sequoia, the right-click → Open trick is gated. If it doesn’t work:

Try to launch Dusk normally (it will be blocked)
System Settings → Privacy & Security → Security
Scroll to “Dusk was blocked” → click Open Anyway
Authenticate with Touch ID or password

Step 4 — Verify Your ROM

Before pointing Dusk at your disc image, verify the SHA-1 in Terminal:

shasum -a 1 ~/path/to/your-dump.iso

Should match exactly:

75edd3ddff41f125d1b4ce1a40378f1b565519e7 (NTSC-U)
2601822a488eeb86fb89db16ca8f29c2c953e1ca (PAL)

If neither matches, see SHA-1 mismatch troubleshooting.

Step 5 — Load Your Disc

Launch Dusk
The prelaunch menu shows the button Select Disc Image
A native macOS file dialog opens with filter “Game Disc Images” (extensions iso, gcm, ciso, gcz, nfs, rvz, wbfs, wia, tgc)
Select your disc dump
Wait for the “Verifying disc image” overlay (a few seconds for XXH128 hash check)
Status changes to “Disc ready.”
Button changes to Play — click it

Step 6 — Configure Controls

⚠️ Keyboard binding is currently broken on macOS (#830). Use a controller for now.

The verified Settings path is:

Settings → Input → Controller → Configure Controller

This opens a per-port window with tabs Port 1, Port 2, … and pages Controller / Buttons / Triggers / Sticks / Rumble, plus an Options section with Enable Dead Zones and Emulate Triggers.

Recommended Mac controllers:

DualShock 4 / DualSense — pair via Bluetooth, native gyro support
Switch Pro Controller — pair via Bluetooth
Xbox Wireless Controller — pair via Bluetooth (model 1914+ for native macOS pairing)
8BitDo Pro 2 — pair via Bluetooth, native gyro

To enable gyro aim:

Settings → Input → Gyro → Gyro Aim (toggle on)

Then Gyro Input Method → Sensor

Mouse aim alternative (added v1.0.0-rc.1):

Settings → Input → Gyro → Gyro Input Method → Mouse

Save File Location

Per the official FAQ (twilitrealm.dev/faq):

~/Library/Application Support/TwilitRealm/Dusk/USA/Card A/01-GZ2E01-gczelda2.gci

For the European disc, replace USA with EUR in the path.

To navigate there in Finder: Go → Go to Folder… (or ⇧⌘G), paste ~/Library/Application Support/TwilitRealm/Dusk/, hit Enter.

Migrate from Dolphin

Dolphin saves on Mac live at ~/Library/Application Support/Dolphin/GC/USA/Card A/. Copy 01-GZ2E01-gczelda2.gci from Dolphin’s folder to Dusk’s folder. Restart Dusk.

Common Issues on macOS

Dusk crashes on first launch (Apple Silicon)

You may be hitting #826 or #805. Workarounds being discussed by the community:

Try the Intel (x86_64) build via Rosetta 2 — slower but may avoid the M-series crash
Try a different Graphics Backend in Settings → Prelaunch → Graphics Backend (cycle Metal / Vulkan / OpenGL)
Check the linked issues for any newer reports of fixes

”Dusk is damaged and can’t be opened”

This is a Gatekeeper variant message. In Terminal:

xattr -cr /Applications/Dusk.app

Then re-open. This removes the quarantine attribute Apple added on download.

Keyboard not working in-game

Known issue #830. Use a controller.

Wrong arch installed (slow performance)

You probably grabbed the x86_64 build on an Apple Silicon Mac and it’s running via Rosetta 2. Re-download the arm64 build.

Audio crackling

Try toggling between sample rates in macOS Audio MIDI Setup, or change the Graphics Backend (sometimes audio is bottlenecked by the renderer).

What to Try Next

🎨 Install the Henriko Magnifico 4K texture pack
🏆 See the achievement list
⚡ Turbo Key shortcut — Hold Tab for 4× speed
📋 All verified known issues

Last updated: 2026-05-10. We update this guide as macOS-specific patches release.

← All install guides · Pillar guide →