RetroArch — Linux Install & Configuration

Automated installation of RetroArch on Debian 13+ and Arch Linux using Ansible. Provides a fully configured multi-system emulation environment for all users.

Target host: 10.32.55.31 — Arch Linux Users: Fredrick, Elin, Alicia, Vanessa, Alexander Hardware: Intel i7-4710HQ, 15GB RAM, Intel HD 4600 + NVIDIA GTX 860M

Also supports the ThinkPad A485 fleet (arch485-01/-02): AMD Ryzen 2500U + Radeon Vega 8, Hyprland/Wayland, PipeWire — see Fleet Deployment.

Quick Start

# Install dependencies + RetroArch + cores
sudo make deps          # System packages
make config             # Deploy retroarch.cfg + assets
make launcher           # Desktop entry + launcher script

# Or using Ansible directly:
ansible-playbook -i inventory/hosts.ini playbooks/install.yml --tags deps

Multi-User Shared Install

# Remote install on archbox
make deps-shared HOST=archbox
make config-shared HOST=archbox
make launcher-shared HOST=archbox

Each user runs retroarch from their session. Saves and configs are per-user under ~/.config/retroarch/. Roms go in /opt/retroarch/roms/ with shared read access.

Requirements

• Debian 13+ or Arch Linux (x86_64)
• Network access to Garage S3 mirror (http://10.32.70.16:3900) — Debian assets only
• Vulkan-capable GPU — auto-detected at deploy: AMD RADV (vulkan-radeon), Intel ANV (vulkan-intel), NVIDIA nouveau (vulkan-nouveau)
• ~2 GB free disk space (base), + roms as needed

ThinkPad A485 Fleet (arch485)

The playbook adapts automatically to the AMD APU laptops:

Aspect	archbox	A485 fleet
GPU	Intel HD 4600 + GTX 860M	Radeon Vega 8 (RADV) — selected automatically
Display	Xorg	Hyprland / Wayland — video_context_driver = "auto"
Audio	ALSA	PipeWire — deploy with -e ra_audio_driver=pipewire
Users	5 local POSIX users	1 AD user (fredrick, via SSSD — gpasswd handles it)
Assets	S3 mirror or packages	packages (retroarch-assets-*) — S3 skipped on Arch

Deploy (run on the laptop itself, shared mode):

# system + config + launcher (adjust user list for a single-user laptop)
ansible-playbook -i inventory/hosts.ini playbooks/install.yml \
    --tags deps,config,launcher \
    -e deploy_mode=shared \
    -e "ra_users=[fredrick]" \
    -e 'ra_user_langs={fredrick: 0}' \
    -e ra_audio_driver=pipewire \
    -l localhost

Variables:

Var	Default	Purpose
ra_users	5 users	Users provisioned (input group + per-user configs)
ra_user_langs	map	Per-user user_language (libretro language ids)
ra_audio_driver	alsa/pulseaudio	Override: pipewire on PipeWire systems
ra_s3_assets	true on Debian	Set false when package assets suffice (Arch)

Vulkan drivers are installed per detected DRM vendor — no DRI_PRIME hacks, no SDL_VIDEO_DRIVER=x11 forcing (Wayland-first, see launcher.sh.j2).

Systems We Play

System	Core	Notes
NES	nestopia / mesen	USB NES controllers from AliExpress
SNES	snes9x / bsnes	Colorful USB SNES controllers (Swedish palette)
Nintendo 64	parallel-n64 / mupen64plus-next
GameCube / Wii	dolphin	Needs Vulkan for best performance
Game Boy / Color	gambatte / sameboy
Game Boy Advance	mgba
PlayStation	beetle-psx (mednafen)
PlayStation 2	play	⚠️ Experimental — FF12, SingStar
PlayStation Portable	ppsspp
Sega Mega Drive	genesis-plus-gx / picodrive
Sega Dreamcast	flycast
Additional cores for arcade (mame), DOS (dosbox-core), Saturn (yabause),
and many more are also installed.

Project Structure

├── ansible.cfg
├── inventory/hosts.ini
├── playbooks/
│   ├── install.yml           # Main playbook
│   ├── vars/{Debian,Archlinux}.yml
│   └── templates/
│       ├── retroarch.cfg.j2
│       └── retroarch.desktop.j2
├── scripts/
│   ├── fetch-assets.sh       # Download assets/cores from S3
│   └── install-remote.sh     # Standalone remote installer
├── Makefile
├── AGENTS.md                 # Full developer/agent docs
├── LICENSE                   # GPL v2 only
└── README.md

OS Support

Feature	Debian 13+	Arch Linux
Package manager	apt	pacman
RetroArch package	retroarch	retroarch
Core packages	libretro-*	libretro-*
Assets package	retroarch-assets	retroarch-assets

The playbook auto-detects OS via ansible_os_family and loads the correct package list from playbooks/vars/{Debian,Archlinux}.yml.

Deploy Modes

Mode	Variable	Description
Single-user	deploy_mode=single (default)	Per-user config, local roms
Shared (multi-user)	deploy_mode=shared	Shared roms at /opt/retroarch/roms/, system launcher

Shared Mode Architecture

/opt/retroarch/
├── roms/                        # Shared ROM directory (read-only for users)
│   ├── snes/
│   ├── nes/
│   ├── genesis/
│   ├── psx/
│   ├── ps2/
│   ├── n64/
│   ├── gamecube/
│   ├── dreamcast/
│   ├── gb/
│   ├── gba/
│   ├── gbc/
│   ├── psp/
│   └── ...
├── bios/                        # Shared BIOS directory
└── assets/                      # Shared assets (system-wide)

Special Game Notes

Final Fantasy XII (PS2)

Runs under play (Play! emulator) via libretro. Performance varies — Play! is experimental but improving. May need per-game config tweaks.

SingStar (PS2)

Requires USB microphones — standard USB audio devices. Play! has limited SingStar support; audio lag can be an issue. Standalone Play! may work better.

Controllers

Controller	Connection	Notes
NES USB (AliExpress)	USB HID	Standard gamepad, needs manual auto-config
SNES USB (AliExpress)	USB HID	Colorful Swedish palette, needs manual auto-config
PS3 DualShock 3	Bluetooth / USB	Built-in RetroArch auto-config, up to 4 over BT

PS3 DualShock 3 pairing:

1. Ensure Bluetooth is running: systemctl start bluetooth
2. Plug controller via USB (auto-pairs via SixAxis plugin)
3. Unplug USB, press PS button
4. Repeat for up to 4 controllers

If auto-pair fails, use bluetoothctl for manual pairing — see AGENTS.md for details.

S3 Mirror (Garage)

Bucket	Endpoint	Region
la-commerce-storage/retroarch/	http://10.32.70.16:3900	eu-north-1

Installation Steps

1. System Dependencies

Debian	Arch Linux
sudo make deps	make deps-shared HOST=archbox

Installs retroarch, all libretro cores, and FOSS Vulkan drivers (vulkan-intel, vulkan-nouveau).

2. Configuration

Deploys retroarch.cfg with per-system core defaults, Swedish locale, Vulkan renderer, ALSA/PulseAudio, and Ozone menu.

3. Launcher

Deploys desktop entry and launcher script (system-wide for shared mode).

Known Issues

1. NVIDIA drivers — GTX 860M runs on nouveau (FOSS). Vulkan performance is lower than proprietary; use Intel HD 4600 IGP via DRI_PRIME=0 for demanding cores.
2. SDDM disabled — system doesn't auto-boot to desktop. Run retroarch --menu from TTY or enable SDDM.
3. Audio latency — default increased to 128ms in config to prevent crackling.
4. BIOS files — not distributable; users must provide their own.
5. Generic USB controllers — no auto-config profiles exist; manual setup needed.
6. PS2 emulation — Play! is experimental; many games have issues.