Skip to main content

Ubuntu, Bazzite, and SteamOS Setup

We recommend Bazzite for a quick start on a gaming PC or cabinet. Steam and gaming tools ship with the OS, and KDE provides a desktop for setup and display configuration. Choose the image matching your hardware through the Bazzite installation guide.

Use your preferred Linux distribution. Bazzite is a starting recommendation, rather than a requirement. Match your release's architecture and runtime requirements. Check your desktop, GPU, controllers, emulators, and plugins before moving your full library.

The current Linux alpha targets x64 Bazzite, Ubuntu Desktop, and SteamOS Desktop Mode on Steam Deck. Testing is ongoing. Other distributions and Steam Gaming Mode need separate validation.

Choose your setup​

DistributionStart hereSoftware installationStartup choice
BazziteKDE Desktop Mode for setupHyperHQ user-folder installer; Flatpak for supported emulatorsDesktop login first; optional dedicated full screen session
Ubuntu DesktopNormal desktop sessionHyperHQ user-folder installer; Ubuntu packages or supported emulator downloadsDesktop login; dedicated session depends on installed compositor and login manager
SteamOS on Steam DeckPower → Switch to DesktopHyperHQ user-folder installer; desktop app store for supported FlatpaksDesktop Mode first; Gaming Mode is a separate test path
Another distributionWorking graphical desktopMatching Linux package and distro-specific dependenciesXDG desktop startup; dedicated session where prerequisites are met

Bazzite​

  1. Install the image for your device and GPU. Choose KDE when planning a separate marquee display with dedicated fullscreen startup.
  2. Complete Bazzite's first-run setup, apply OS updates, and restart if requested.
  3. If Steam Gaming Mode opens, select Power → Switch to Desktop.
  4. Set your resolution, scaling, sound output, and controllers in desktop settings. Connect every cabinet display before saving the layout.
  5. Follow Install HyperHQ. Extract the setup ZIP, then run the .run installer from the extracted folder.
  6. Complete the HyperHQ wizard and install core plugins. Install a Linux emulator through its supported setup flow.
  7. Launch one game through HyperSpin. Test controls, pause, resume, exit, sound, and return to the frontend.

Keep HyperHQ under your home folder. Bazzite manages the base OS as an image. The HyperHQ desktop installer does not need package layering or a writable system image. Use Bazzite's software installation guide for other applications. Ubuntu apt commands do not apply to Bazzite.

For a portable HyperSpin download, prefer the tar.gz archive when avoiding FUSE dependencies. Keep the extracted runtime files together. Set up Flatpak emulator folder access for ROMs, BIOS files, and saves before launching from HyperHQ.

Ubuntu Desktop​

  1. Install Ubuntu Desktop and apply OS updates. Use the distribution's driver tools for your GPU.
  2. Confirm video acceleration, sound, controllers, and display layout in the desktop.
  3. Follow Install HyperHQ, then complete the wizard and core plugin installation.
  4. Install the Linux emulator for one system. Test a game directly, then launch the same game through HyperSpin.
  5. Test pause, resume, exit, and return before configuring startup.

Optional Ubuntu runtime setup​

For Ubuntu Desktop 24.04 or newer, HyperSpin provides an Ubuntu runtime installer. Download the script from the repository and review the planned changes first. Run from the download folder as your normal desktop user:

bash install-ubuntu-runtime.sh --dry-run
bash install-ubuntu-runtime.sh

The script requests sudo, enables Universe, and installs runtime libraries, FUSE compatibility, FFmpeg, X11 window tools, audio tools, 7-Zip, and input helpers. By default, the script adds your user to hyperspin-uinput for virtual keyboard and mouse input. Log out fully and sign back in, or reboot, after installation.

To install dependencies without changing virtual input access:

bash install-ubuntu-runtime.sh --no-input-access

Emulator key injection then needs existing /dev/uinput access. Repair or install HyperspinCore Essentials through HyperHQ for bundled helpers. Steam, emulators, GPU drivers, and a desktop are separate installations. Run this Ubuntu script only on Ubuntu.

For an AppImage reporting a FUSE error on Ubuntu 24.04, the compatibility package is libfuse2t64. Use the archive or extract-and-run alternative if you prefer to avoid FUSE. See the AppImage FUSE guide.

Ubuntu GNOME Wayland imposes window-control restrictions. Installing X11 tools does not remove those restrictions. If your Ubuntu version offers an Xorg session, compare the affected workflow there. Record the session type in support reports. A dedicated session with Gamescope exposes one display; separate marquee startup requires KWin.

SteamOS on Steam Deck​

  1. Apply SteamOS updates through Steam settings.
  2. Select Power → Switch to Desktop. A keyboard and mouse help with installation and path entry.
  3. Download and extract the Linux x64 HyperHQ setup ZIP. Open the .run file. Enable Is executable in Properties → Permissions if required.
  4. Keep the default ~/HyperSpin root on internal storage. Use your mounted microSD card for ROMs and media if desired.
  5. Complete the wizard and core plugin installation. Install supported Linux emulators from the desktop app store or their official package source.
  6. Grant Flatpak emulators access to your library folders. Verify the microSD mount path through the file manager rather than copying another user's path.
  7. Test a game through HyperSpin in Desktop Mode, including controls, sound, pause, resume, and exit.

Valve documents Desktop Mode and desktop software in the Steam Deck desktop FAQ. Keep app files in your home folder. The standard HyperHQ installation does not require disabling SteamOS read-only protection or installing system packages with pacman.

Optional Steam Gaming Mode test​

First finish Desktop Mode setup. This path is separate from the current alpha's Desktop Mode scope.

  1. In desktop Steam, choose Games → Add a Non-Steam Game to My Library.
  2. Select the installed HyperSpin launcher, or browse to the portable archive's hyperspin executable. Select the app rather than the setup .run file.
  3. Check the shortcut's target and working directory. Keep paths with spaces quoted.
  4. Leave forced Proton compatibility off for native Linux HyperSpin. Configure Proton for Windows games through their own Steam entries.
  5. Return to Gaming Mode and test navigation, launch, pause, exit, Steam Input, and suspend/resume.

Use Valve's Non-Steam shortcut instructions for the Steam menu flow. A shortcut does not install plugins or grant sandbox folder access. If the workflow fails, return to Desktop Mode and compare the same game there.

Finish your Linux setup​