Skip to main content

Install and Maintain on Linux

Linux alpha​

For x64 PCs and Steam Deck. Alpha targets are Bazzite, Steam Deck running SteamOS Desktop Mode, and Ubuntu Desktop. Full desktop and device testing is still in progress. Compatibility is not yet confirmed on every target.

Install HyperHQ​

Start with the distribution setup guide for Ubuntu, Bazzite, or SteamOS. The installation flow below applies to all three.

  1. Open your desktop. On Steam Deck or Bazzite Gaming Mode, choose Power → Switch to Desktop.
  2. Download the latest Linux x64 HyperHQ setup ZIP from HyperSpin and extract the archive.
  3. Double-click the HyperHQ setup .run file in the extracted folder. If prompted, choose Run or Execute.
  4. Follow the setup prompts and keep the default installation location.
  5. Choose Launch HyperHQ when setup finishes, or open HyperHQ from your applications menu later.

No terminal commands or administrator access are needed for this desktop installation. Setup installs the app into ~/HyperSpin/HyperHQ and adds application-menu and desktop shortcuts.

If your file manager asks for permission to run the file, open Properties → Permissions. Enable Allow executing file as program or Is executable, then double-click the .run file again. Extract the ZIP before running setup.

The default HyperSpin root is ~/HyperSpin, regardless of XDG_DATA_HOME. Menu entries and icons still use XDG locations. Complete the setup wizard, install core plugins, sign in, and configure one system.

This is an early alpha. Expect bugs. Include your device, OS version, what happened, and the error message or a screenshot when reporting an issue.

Desktop Mode help: Steam Deck · Bazzite.

Other package formats​

Use the setup ZIP above for the alpha desktop walkthrough. Source build targets also include AppImage, portable payloads, deb, and rpm. These targets do not establish alpha support for additional architectures or distributions. Check the release assets before choosing another format.

HyperSpin defines AppImage and archive targets. HyperOverlay and HyperMarquee have separate package targets. Keep ecosystem apps and plugins on compatible channels and architectures.

The following terminal examples are optional portable-package instructions. They are not required for the desktop setup above.

Start HyperSpin​

Launch HyperSpin through HyperHQ after core installation. HyperHQ recognizes a standalone HyperSpin AppImage and an extracted archive containing hyperspin.

For a manually downloaded AppImage, replace the example filename:

chmod +x ./HyperSpin_VERSION_x86_64.AppImage
./HyperSpin_VERSION_x86_64.AppImage

If FUSE is unavailable, use the archive or run:

./HyperSpin_VERSION_x86_64.AppImage --appimage-extract-and-run

Keep an extracted app directory together. The executable needs its adjacent runtime files.

Files and permissions​

  • Use Linux paths such as /home/chris/Games/Arcade.
  • Match filename case. Games and games are different paths on case-sensitive filesystems.
  • Choose a stable mount location for external drives. Mount the drive before starting your cabinet apps.
  • Keep application binaries on storage permitting execution. chmod +x does not override a noexec mount.
  • Keep scripts in LF format with a valid interpreter line.
  • Give your user access to the selected library and required hardware. Avoid running the full desktop stack as root.
  • For Flatpak emulators, grant access to the specific ROM, BIOS, media, and save folders required by the emulator.

Flatpak applications run inside a sandbox with separate filesystem access. See Flatpak concepts.

Start at login​

Open Settings, Startup, Apps in HyperHQ. Each app offers Off, Time-based, or Full screen startup.

For normal desktop login, choose Time-based and set Launch delay from 0 to 600 seconds. Allow time for drives and controllers. Linux writes user-owned XDG entries under $XDG_CONFIG_HOME/autostart, with ~/.config/autostart as the fallback.

SteamOS Gaming Mode does not run desktop login entries. The current alpha targets Desktop Mode. Adding HyperSpin as a Non-Steam Game is a separate test path, not confirmed Gaming Mode compatibility.

Optional full screen startup​

Follow Fullscreen and Cabinet Startup for setup, display selection, desktop return, and recovery.

Full screen startup creates a dedicated app login session. This advanced option requires administrator authentication through polkit. Standard desktop installation does not.

The installed app checks for KWin with dbus-run-session, or Gamescope, plus Python 3 and a supported active login manager: SDDM, Plasma Login Manager, or GDM. GDM also needs busctl and AccountsService. Review the availability message in Startup Apps before saving.

Choose one primary full screen app. The other app supports delayed startup in the same session. KWin supports the saved main and marquee display selections. Gamescope is a single-display fallback; a separate marquee requires KWin.

Use Exit to Desktop to leave the dedicated session. Review Reopen HyperHQ after Exit to Desktop to control its return to the tray. To restore your previous login configuration, change full screen startup to Time-based or Off and save. If restoration reports a conflict, keep the saved configuration backup and include the error in your report.

Physical login, reboot, desktop handoff, and device acceptance are still in progress. Full screen startup is not a requirement for trying the alpha.

Updates and backups​

  1. Create a database backup in Settings, Database Backup.
  2. Copy the backup, HyperSpin library, external ROM folders, BIOS files, emulator settings, and saves to separate storage.
  3. Close games and ecosystem apps before replacing application files.
  4. Update through the release's documented package flow. Use the distribution package manager for distribution-managed packages.
  5. Reopen HyperHQ. Test sign-in, plugins, one game, pause, exit, and media playback.

Keep data outside the replaceable HyperHQ application directory. The .run installer replaces an existing app installation without keeping the previous app directory as a backup.

The active Linux profile normally lives in ~/.HyperHQ/, including main.hsdata and backups/. HYPERHQ_DATA_DIR overrides this profile root. XDG_DATA_HOME does not change the setup default.

HyperHQ's Linux uninstall flow distinguishes the parent HyperSpin data from user data under ~/.HyperHQ, $XDG_CONFIG_HOME/HyperHQ, and $XDG_CACHE_HOME/HyperHQ, using home-directory defaults where unset. Use the app's Open Folder actions to locate your active database backups and logs.

Move from Windows​

Copy your library and backups first. Install Linux apps, helpers, plugins, and emulators separately. Windows binaries and absolute paths need replacement.

Update the HyperSpin root, ROM directories, emulator paths, BIOS paths, media overrides, and save locations. Check filename case, archive contents, shared-drive permissions, and Linux RetroArch cores. Test save compatibility with the exact emulator version before loading important progress.

The Windows Repair HyperSpin Location.cmd instructions do not apply to Linux. After a Linux move, reselect the HyperSpin path in HyperHQ and review external paths separately. Keep the previous copy until every platform passes a launch and save check.

Uninstall​

For the default setup location:

"$HOME/HyperSpin/HyperHQ/uninstall-hyperhq"

Use the uninstaller inside your chosen application directory for a custom installation. Keep both HyperSpin data and user data when preserving your library. Remove distribution packages through their package manager.