Manage your favorites, launch games across 35+ Retro Systems, customize themes, and refresh box art - all from a sleek, native Linux, Rofi-powered interface.
- ✅ Fully installable from a fresh Linux system
- ✅ Modular setup (emulators, themes, tools)
- ✅ Clear step-by-step instructions
- ✅ 40+ console setup supported
- ✅ Active development
✨ Easy plug-and-play setup
Clone and start playing immediately — no complex installation needed.
🎮 Compatible with 35+ retro consoles
Check out the CONSOLE LIST for the full supported list.
⭐️ Favorites management
Automatic ROM and save file symlinks for smooth game launching.
🎨 Theme Editor
Customize backgrounds, and text, fully integrated into Retro-Fi.
🖼️ Box art refresh tool
Refresh and manage your box art cache with ease.
🖌️ Ships with high-quality console PNG Icons
All with transparent backgrounds for a sleek UI.
🗂️ Custom console → games folder structure
Keeps your library organized and clean.
🎨 Custom .rasi Rofi theme
Designed for Retro-Fi, fully included.
🖥️ Transparent grid layout Displays box arts & game descriptions in a visually appealing way.
🔍 Per-system and per-game search method
Quickly find and launch any title in your library.
🎨 Custom theme isolated from global Rofi config
Safe to tweak without affecting other Rofi setups.
🪶 Extremely lightweight menu
💻 Written entirely in pure Bash
Minimal dependencies, fully transparent, and modifiable.
Retro-Fi assumes basic familiarity with Linux, including:
- opening a terminal
- copying and pasting commands
- using sudo
If you are new to Linux, consider reviewing a beginner Linux guide first.
To run Retro-Fi, your system should have the following installed:
- Git - to clone this repository
- Bash – version 5.x recommended
- Rofi – for the graphical menu interface
- Rsync - used during installation for ease of use
- Flatpak – for certain emulators and runtime support
- Flathub - via flatpak to be able to install emulators
- RetroArch – for multi-system emulation support
- Xfce4-Terminal - Optional for script readability
- Various retro emulators are optional and depend on which consoles you want to use:
- Some are installed via your terminal package manager (apt, pacman, etc.).
- Others require Flatpak.
- Some use RetroArch cores (downloadable via terminal or buildbot.libretro.com).
- Some systems (e.g., PS1, PS2, Sega CD, XBOX) require BIOS files for proper emulation.
⚠️ Retro-Fi itself does not install emulators automatically. Make sure the emulators you intend to use are installed and accessible via your PATH or Flatpak.
Favorites, box art, and launch functionality require the corresponding emulator to be present for the selected system.
Tested on Arch Linux (Other OSes should work)
Warning
- Arch
sudo pacman -S git rsync- Ubuntu/Debian
sudo apt update && sudo apt install git rsync - Fedora
sudo dnf install git rsyncgit clone https://github.com/ethanlabs101/Retro-Fi.git ~/retro-fi-tmp
⚠️ Retro-Fi expects the directory structure to match for full functionality.
Run the following commands:
cd ~/retro-fi-tmpsudo rsync -av ~/retro-fi-tmp/local/ ~/.local/sudo rsync -av ~/retro-fi-tmp/config/ ~/.config/sudo rsync -av ~/retro-fi-tmp/cache/ ~/.cache/sudo rsync -av ~/retro-fi-tmp/Pictures/ ~/Pictures/sudo rsync -av ~/retro-fi-tmp/Games/ ~/Games/- Arch
sudo pacman -S rofi flatpak retroarch- Ubuntu/Debian
sudo apt install rofi flatpak retroarch- Fedora
sudo dnf install rofi flatpak retroarch- Install flathub via flatpak
sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo-
Xfce4-terminal (Optional for script readability - use your distros package manager)
-
(Arch)
sudo pacman -S xfce4-terminal- Create the directory for the backgrounds/system icons if it doesnt exist
sudo mkdir -p /usr/share/rofi/themes/- Go to ~/retro-fi-tmp
cd ~/retro-fi-tmp- Move the main current background
sudo cp retro-fi.png /usr/share/rofi/themes/- Copy all extra backgrounds
sudo cp -r retro-fi-backgrounds /usr/share/rofi/themeschmod +x ~/.local/bin/retro-games
chmod +x ~/.local/bin/run-theme-editor.sh
chmod +x ~/.local/bin/rofi-theme-manager.sh
chmod +x ~/.local/bin/run-favorites-update.sh
chmod +x ~/.local/share/retro-games/favorites/retro-favorites-update.sh
chmod +x ~/.local/bin/retrofi-boxart-refresh.sh
chmod +x ~/.local/bin/run-boxart-upload.shRun:
echo $PATH | grep -q "$HOME/.local/bin" && echo "PATH is OK" || echo "PATH missing ~/.local/bin"If you see PATH is OK skip to step 8 if not, continue step 7a.
- 7a. Add the following snippet to your shell to fix PATH
If your shell is Bash use:
nano ~/.bashrcThen paste this at the end of the file
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrcThen in terminal run:
source ~/.bashrcIf your shell is Zsh use:
nano ~/.zshrcThen paste this at the end of the file
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrcThen in terminal run:
source ~/.zshrcMake sure to open a new terminal after the source command then repeat the command from step 7 to check that paths are correct.
Retro-Fi does not automatically install emulators or cores. Some systems use:
- Native package manager installs (pacman / dnf /apt)
- Flatpak (via Flathub)
- RetroArch cores (terminal or manual buildbot install)
- ➡️ See the full setup guide here: Emulator Setup Guide
-
9a. ROMs
- This launcher expects games to be stored in the ~/Games directory with a correctly named sub-folder for each system.
- Use the provided Game and console sub folders and add your roms to the correct folder.
- Example: ~/Games/DS holds all the .nds Nintendo DS ROMs
-
9b. Box art
Box art images go in:
~/Pictures/retro-games
Then run the boxart uploader script using the command:
retrofi-boxart-refresh.shAlternatively, you can launch the script inside the Rofi menu by selecting the Upload Boxart option.
- The supported formats are .avif, .png, .jpeg, and .jpg
- Boxart names much match the game name exactly minus extension.
- (ex. MarioKartDS.nds MarioKartDS.png)
Once all steps have been followed thoroughly run the command:
retro-games- The retro games menu should appear with the custom theme.
- Custom console icons should display.
- Navigate with arrow keys or search for a console , select console, then search for a game.
- The selected game will display a dark grey background behind the selected entry.
- Selecting a game should launch it with the correct emulator.
- Select Theme editor to edit theme and text.
- Launch a game then close and select Recently Played to return to your game.
- Select Update favorites to edit your favorites list.
- Select Favorites List to view and launch your current favorite games.
- Select Upload Boxart to upload your boxart to the cache.
- Menu appears empty: Check that your ~/Games directory exists and contains correct folders and ROMs
- Icons missing: make sure box art images are in ~/.cache/rofi-game-icons and named exactly like ROM file (Minus game extension)
- Emulator not launching: verify the emulators are installed with the command: which emulator (example: which fceux)
Once confirmed , consider adding a keybind to your WM or DE to launch the menu instantly, or type retro-games in terminal for easy access.
RetroFi currently does not support automatic multi-disc management.
Systems affected may include:
- PlayStation 1
- Sega CD
- Saturn
- Dreamcast
- PlayStation 2
- Atari Jaguar CD
- CD-i
For multi-disc titles, it is recommended to launch and manage disc swapping directly inside your emulator.
This is intentional to keep RetroFi lightweight, modular, and stable.
Multi-disc support may be considered in the future if there is demand.
RetroFi uses a specific directory layout.
~/.local/bin/retro-games
~/.local/share/retro-games/favorites/retro-favorites-update.sh
~/.local/bin/rofi-theme-manager.sh
~/.local/bin/retrofi-boxart-refresh.sh
~/.local/bin/run-boxart-upload.sh ~/.local/bin/run-favorites-update.sh
~/Games/{console}/{roms}
~/.local/share/retro-games/favorites/
~/Pictures/retro-games/
~/.cache/rofi-game-icons/
~/.config/rofi/game-theme/retro-fi.rasi
/usr/share/rofi/themes/retro-fi-backgrounds/
/usr/share/rofi/themes/retro-fi.png
~/retro-fi-mds
- (unused in project use rm -rf ~/retro-fi-mds to remove)
~/retrofi-git-screenshots
- (unused in project use rm -rf ~/retrofi-git-screenshots to remove)
Favorites and Recently Played are supported for most disc-based and cartridge systems.
However, behavior may vary depending on:
- Emulator used
- Core configuration
- Save file location
- Flatpak vs native install
Some systems have limitations.
➡️ Full compatibility breakdown:
View Favorites Compatibility →
➡️ Recently Played behavior details:
View Recently Played Info →
RetroFi ships modular. Each component can be customized independently.
Interactive helper script that allows:
- Background switching
- Text color adjustments
- Custom Fonts
- Italics / Bold text modifier
Does not modify your global Rofi configuration.
RetroFi includes:
- High-quality stock backgrounds
- Translucent console PNG system icons
- Support for user-added backgrounds
Background assets are located in: /usr/share/rofi/themes/backgrounds/
You can add your own PNG files and select them using the Theme Editor.
Manages:
- Favorites list generation
- ROM symlink creation
- Save file linking (where supported)
Keeps your favorites structured without duplicating ROM data.
Refresh tool that:
- Pulls images from ~/Pictures/retro-games
- Updates RetroFi cache
- Cleans invalid entries
- Preserves naming structure
Supports: .png, .jpg, .jpeg, .webp, .avif
RetroFi intentionally supports systems up to:
- PlayStation 2
- GameCube / Wii
- PSP
- Original Xbox
- Nintendo 3DS
- PlayStation 3
- Xbox 360
- Nintendo Switch
- Modern-generation consoles
This project focuses on lightweight, efficient retro and early 3D systems.
High-end emulation platforms are outside the scope of RetroFi by design.
RetroFi does not provide:
- BIOS files
- ROM downloads
- Direct download links
- Piracy guidance
Users are responsible for legally obtaining their own:
- Game ROMs
- Required BIOS files
- Disc images
This project is a launcher and management interface only.
This project is open source and released under the MIT License. See LICENSE for details.
