Ryujinx Guides and Troubleshooting

Practical step-by-step solutions for setup, common errors, and long-term best practices.

Install Product Keys and Firmware

Dump prod.keys and title.keys from a Nintendo Switch you own using homebrew tools.

Open Ryujinx, go to File → Open Ryujinx Folder, and copy keys into the system folder.

Alternatively use Tools or Actions → Install Keys if your build provides it.

Install firmware via Tools → Install Firmware and select your firmware ZIP, folder, or XCI.

Restart the emulator when prompted. Outdated keys cause RYU-0003 firmware parsing errors.

Add Game Folders

Open Options → Settings → Game Directories.

Click Add and select the folder containing your .nsp, .xci, or .nca files.

Click Apply and OK. The library rescans automatically.

If no games appear, confirm keys are installed and paths are readable.

Choose the Right Graphics Backend

Open Options → Settings → Graphics. Update GPU drivers before testing any backend.

Vulkan

Try first on modern NVIDIA and AMD GPUs. Best performance and compatibility on Windows and Linux.

Recommended

OpenGL

Fallback when Vulkan fails to initialize or vulkan-1.dll is missing.

Fallback

Metal

Default backend on macOS and Apple Silicon builds. Optimized for Metal-capable hardware.

macOS

Improve FPS and Reduce Stutter

Enable asynchronous shader compilation in graphics settings.

Let PPTC build on first launch; do not delete cache folders mid-session.

Lower resolution scale if GPU-bound; close background apps if CPU-bound.

Use Vulkan on Steam Deck Linux builds for best results.

Memory baseline

Keep at least 8 GB RAM free; 16 GB system RAM is recommended for stable performance.

Configure Controllers

Options → Settings → Input, select Player 1.

Pick your device: Xbox, DualSense, Pro Controller, or keyboard.

Map buttons, save, and test in-game. Unbind with the clear control in the UI.

Install Mods and DLC

Modding Guide

DLC, updates & cheats

Right-click a title or use the manager to install NSP updates and DLC. Place RomFS or Exefs mods in the mod folder path shown in settings. Enable cheats from the per-game menu when supported.

Antivirus Warnings Explained

Heuristic scanners flag unknown emulators. Verify SHA-256 hashes, download from trusted release pages only, and avoid repacks. If you quarantined a good build, restore it after hash confirmation and add a folder exclusion.

Common Problems Quick Reference

Emulator will not open on Windows

Install the latest .NET Desktop Runtime when prompted. Run from a normal user folder, not Program Files.

Missing keys or hash errors

Refresh prod.keys and title.keys from your console dump. Reinstall game updates if NCA verification fails.

Game stuck at 30 FPS

Some titles cap framerate by design. Use VSync and frame limit settings; uncap only when the game supports it to avoid double speed.

Crashes after update

Clear shader and PPTC cache for that title, then rebuild. Confirm firmware matches the game requirements.

Best Practices

Back up saves before major emulator updates.

Keep GPU drivers and Ryujinx builds current.

Use Canary only when you accept occasional regressions.

Read per-game notes in compatibility lists before long play sessions.

Download