EmuDeck not installing or set up correctly on Steam Deck — common first-run fixes

make-the-emudeck-appimage-executable (sortOrder=1, isMostHelpful)

The single most common reason EmuDeck refuses to open: Linux downloaded files are not executable by default. Fix it with one command in desktop mode.

1. Switch to Desktop Mode. On your Steam Deck, press the Steam button, go to Power → Switch to Desktop. EmuDeck must be installed and run from Desktop Mode — not Game Mode.
2. Open a terminal (Konsole). Click the application launcher (bottom-left), search for Konsole and open it. Alternatively, right-click the desktop and choose Open Terminal.
3. Make the AppImage executable. Run the following command (adjust the path if your AppImage is not on the Desktop):
   chmod +x ~/Desktop/EmuDeck.AppImage
4. Launch EmuDeck. Double-click the EmuDeck AppImage on the desktop. The first-launch wizard will open and guide you through the full setup. If it still does not open, right-click the file → Properties → Permissions and ensure "Is executable" is ticked.

If you downloaded a newer version of EmuDeck over an older install, repeat this step — the new AppImage is also not executable by default.

fix-flatpak-and-network-issues-during-installation (sortOrder=2)

EmuDeck installs emulators as Flatpaks from Flathub. If the installation hangs or an emulator fails to install, the fix is almost always a network or Flatpak repository issue.

1. Ensure you have a stable internet connection. EmuDeck downloads several hundred megabytes of Flatpak packages. A Wi-Fi dropout mid-install will cause it to hang. Connect via ethernet if possible, or move closer to your router.
2. Add the Flathub repository if it is missing. Open Konsole and run:
   flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
   Some Steam Deck setups ship without Flathub pre-configured. EmuDeck requires it.
3. Repair your Flatpak installation. If packages are partially downloaded or corrupted, run:
   flatpak repair
   This checks and fixes the local Flatpak database without removing your installed apps.
4. Re-run EmuDeck setup. After fixing the Flatpak issues, re-open EmuDeck and choose Manage Emulators → reinstall the emulator that failed, or run the full setup wizard again. EmuDeck is designed to be re-run safely — it will not overwrite your existing configuration or game library.

fix-rom-folder-structure-so-games-appear-in-es-de (sortOrder=3)

If EmuDeck installed correctly but your games do not appear in ES-DE or another frontend, the most likely cause is that your ROMs are not in the expected folder structure.

1. Understand the expected path. EmuDeck creates a ROM library at ~/Emulation/roms/ on your Steam Deck's internal storage. Each system has its own subfolder — for example, ~/Emulation/roms/ps2/ for PlayStation 2, ~/Emulation/roms/switch/ for Nintendo Switch, and so on.
2. Confirm the correct subfolder name. Open the ~/Emulation/roms/ directory in the file manager (Dolphin). You will see folders EmuDeck created for each supported system. Place your ROM files directly inside the matching system folder — not in subfolders within it.
3. MicroSD card alternative. If your ROMs are on a microSD card, EmuDeck can use a different base path. During setup, or via EmuDeck → Settings → Change ROM directory, you can point EmuDeck to /run/media/mmcblk0p1/Emulation/roms/ (the typical SD card path). Create the same system subfolders there.
4. Update the games list in ES-DE. After placing your ROMs, open ES-DE and press Start → Scraper or choose Start → Other Settings → Rescan to force ES-DE to re-index your library. Your games should now appear.

add-frontends-and-emulators-to-steam-game-mode (sortOrder=4)

EmuDeck does not automatically add ES-DE or individual emulators to Steam. You need to add them manually so they appear in Game Mode and work with the Steam Deck controller layout.

1. Open EmuDeck and run "Add to Steam". Launch the EmuDeck AppImage in Desktop Mode, go to Tools and Stuff → Add to Steam. This will add ES-DE and any other frontends/emulators you select as Non-Steam games in your library.
2. Alternatively, use the Steam shortcut manually. Open Steam in Desktop Mode → Games → Add a Non-Steam Game to My Library → browse to the emulator's executable (most Flatpaks are at /var/lib/flatpak/exports/bin/).
3. Set a controller layout. After adding ES-DE to Steam, switch to Game Mode, launch it once, then go back to the Steam overlay and choose Controller Settings → Browse Community Layouts. There are official EmuDeck-recommended layouts that set up the on-screen keyboard and hotkeys correctly.

Tip: launch ES-DE from Game Mode rather than individual emulators — it gives you one unified library across all platforms and handles controller profiles automatically.