Install Dusk on Linux — Twilight Princess PC Port

Install Dusk on Linux (x86_64 + ARM64). Avoid the AppImage permission bug, find real save paths, and pick the right graphics backend for your distro.

Published 2026-05-10 ·Updated 2026-06-20

This guide covers installing Dusklight (formerly Dusklight) — the native Twilight Princess PC port — on Linux desktop. For Steam Deck, see the dedicated Steam Deck guide (the Deck uses the same Linux x86_64 binary but the setup flow is different).

Time required: ~10 minutes Difficulty: Easy

⚠️ Important change — AppImage-only on Linux

Dusklight ships only .AppImage builds for Linux. Both architectures are published every release: x86_64 and a native ARM64 AppImage. The .zip variants from older releases are no longer used.

The AppImage permission bug (#818) that previously caused fatal launch errors like:

[fatal] [dusk] Unable to get PrefPath: Couldn't create directory '/TwilitRealm': 'Permission denied'

…appears to have been worked around, since AppImage is now the published Linux distribution path. If you still see that error on v1.4.1, file an issue.

If you previously ran an old AppImage and left an orphan /TwilitRealm directory at root, clean it up: sudo rm -rf /TwilitRealm (run only if you know that path is yours).

Before You Start

1. Identify your architecture

Run in terminal:

uname -m

x86_64 → most desktops, laptops, and Steam Deck → use the x86_64 build
aarch64 / arm64 → Raspberry Pi 5, ARM laptops → use the arm64 build

2. Vulkan support (recommended)

Dusklight supports 7 graphics backends, but Vulkan and OpenGL are the typical Linux defaults. Verify Vulkan is available:

Ubuntu / Debian:

sudo apt install vulkan-tools mesa-vulkan-drivers
vulkaninfo --summary

Arch:

sudo pacman -S vulkan-tools vulkan-icd-loader

Fedora:

sudo dnf install vulkan-tools mesa-vulkan-drivers

If Vulkan doesn’t work for some reason, you can switch to OpenGL or OpenGL ES in Settings → Prelaunch → Graphics Backend.

3. Your own GameCube Twilight Princess disc dump

Required. See How to legally dump your TP disc.

Supported discs:

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

Step 1 — Download Dusklight

Grab the AppImage from github.com/TwilitRealm/dusklight/releases:

Arch	File	Size	Notes
x86_64	`Dusklight-v1.4.1-linux-x86_64.AppImage`	32.0 MB	Current v1.4.1 — AppImage only
ARM64	`Dusklight-v1.4.1-linux-arm64.AppImage`	30.7 MB	Native ARM64 AppImage, ships every release

Verify the download:

sha256sum ~/Downloads/Dusklight-v1.4.1-linux-x86_64.AppImage

Compare the output against whatever the GitHub releases page publishes for that asset.

Step 2 — Make Executable

cd ~/Downloads
chmod +x Dusklight-v1.4.1-linux-x86_64.AppImage
mkdir -p ~/Applications && mv Dusklight-v1.4.1-linux-x86_64.AppImage ~/Applications/

You may also need libfuse2 for AppImages on some distros:

Ubuntu/Debian: sudo apt install libfuse2
Arch: sudo pacman -S fuse2
Fedora: usually pre-installed

Step 3 — Verify ROM

sha1sum ~/path/to/your-dump.iso

The SHA-1 should match 75edd3ddff41f125d1b4ce1a40378f1b565519e7 (NTSC-U) or 2601822a488eeb86fb89db16ca8f29c2c953e1ca (PAL).

Step 4 — First Launch

~/Applications/Dusklight-v1.4.1-linux-x86_64.AppImage

The Dusklight prelaunch window opens. Click Select Disc Image, browse to your disc dump, and wait for “Verifying disc image” to complete. When the status reads “Disc ready.”, click Play.

Step 5 — Configure Controller / Gyro

Verified path:

Settings → Input → Controller → Configure Controller

Per-port window opens with tabs Port 1, Port 2, … and pages Controller / Buttons / Triggers / Sticks / Rumble.

To enable gyro aim:

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

Linux supports DualShock 4/5, Switch Pro Controller (with hid-nintendo kernel module on most distros), 8BitDo Pro 2, Xbox Wireless via xpadneo, and more.

To use mouse aim instead:

Settings → Input → Gyro → Gyro Input Method → Mouse

Save File Location

~/.local/share/TwilitRealm/Dusklight/USA/Card A/01-GZ2E01-gczelda2.gci

For the PAL disc, replace USA with EUR. (Dusklight auto-migrates save data from the legacy Dusk folder on first launch.)

If ~/.local/share/TwilitRealm/Dusklight/ doesn’t exist after first launch, see the #818 troubleshooting section below.

Migrate from Dolphin

Dolphin Linux saves: ~/.local/share/dolphin-emu/GC/USA/Card A/01-GZ2E01-gczelda2.gci. Copy to Dusklight’s folder. Restart Dusklight.

Distro-Specific Notes

Ubuntu / Debian

Works out of the box on 22.04+. For older releases you may need to install libsdl3-0 from a backports repository or build SDL3 from source.

Arch / Manjaro

Works. Ensure vulkan-tools and your matching driver package (vulkan-radeon or nvidia-utils) are installed.

Fedora

Works. Same Vulkan story as Arch.

NixOS

The repo includes a flake.nix and flake.lock. Building from source is the supported path.

Other distros

Try the binary; if Vulkan fails, switch the graphics backend in Settings → Prelaunch.

Common Issues

”Couldn’t create directory ‘/TwilitRealm’: ‘Permission denied’”

This was an early AppImage variant bug (#818). Since AppImage is now the official Linux format, the underlying behavior has been adjusted. If you still see this on v1.4.1, file a new issue and clean up any orphan /TwilitRealm directory at root: sudo rm -rf /TwilitRealm (only if you’re sure it’s yours).

Vulkan not found

Install mesa-vulkan-drivers (Ubuntu/Debian) or vulkan-radeon/nvidia-utils (Arch) and reboot. Or switch to OpenGL in Settings → Prelaunch → Graphics Backend.

Audio doesn’t work

Most distros use PipeWire as default; Dusklight should pick it up automatically. If not, install pipewire-pulse for the PulseAudio compatibility shim.

Game runs but can’t bind keyboard

Linux keyboard binding is reportedly working (the macOS issue #830 is macOS-specific). If you hit binding issues on Linux, check the GitHub issues page for newer reports.

Stutters at unlocked framerate

Known issue: pulsating bloom artifact at unlocked framerate (#825). Either lock framerate or accept the visual quirk.

Need to compile from source

Per docs/building.md:

Ubuntu 24.04, Arch, Fedora supported
CMake 3.25+
Python 3+
Build presets: linux-default-relwithdebinfo, linux-default-debug, linux-clang-relwithdebinfo, linux-clang-debug

Common Problems on Linux

“Couldn’t create directory ‘/TwilitRealm’: Permission denied” (AppImage) → #818 fix
Hash verification failed → fix guide
Unsupported game error → region guide
Stuck at 30 FPS → checklist
Dolphin save not loading → migration guide
Full hub → all known issues

What to Try Next

🎨 Install the Henriko Magnifico 4K texture pack (path: ~/.local/share/TwilitRealm/Dusklight/texture_replacements/)
🚀 Framerate & 60 FPS, explained
💾 Save file paths & cross-device sync
🎮 Steam Deck-specific guide (uses this same Linux x86_64 build)

Last updated: 2026-06-20. We update this guide as Linux-specific patches release.

← All install guides · Pillar guide →