There are two ways to add a theme to Recalbox: the built-in catalogue, which does everything from the machine, and manual installation, for themes distributed elsewhere.
START → MAIN MENU → THEME MANAGER (RUN).LEFT/RIGHT and the previews with UP/DOWN.A (INSTALL).Please confirm. Do you want to install the theme <name>? → YES.Downloading theme <name>, Downloaded X%) then installs it (Installing theme <name>, Installed X%, Cleaning...).Do you want to switch to the newly installed theme <name> ? → YES applies the theme right away, NO simply leaves it installed.Installation happens without rebooting and does not touch the theme currently in use until you answer YES to that last question.
The archive is downloaded to a temporary folder on the boot partition, then extracted into
/recalbox/share/themes/<theme-folder>. A heavy theme therefore needs free space both on theBOOTpartition and on yourSHAREstorage.
When a newer version of an installed theme is published in the catalogue, the A button reads UPDATE instead of SWITCH TO.
The flow is the same as an installation, with the message Please confirm. Do you want to update the theme <name>?. The old version is only replaced once the new one has been extracted successfully: if anything fails along the way, your current theme stays intact.
Manually installed themes have no known version: they are never offered for update. To update one, copy the new folder over the old one.
Move to an installed theme and press X (DELETE), then confirm: Please confirm. Do you really want to delete the theme <name>?.
The theme folder is removed from /recalbox/share/themes. If you delete the active theme, Recalbox automatically falls back to the default theme shipped with the system.
Themes shipped with Recalbox (recalbox-next, recalbox-next-v9, recalbox-240p) cannot be removed: the DELETE button does not appear on them.
| Message | Cause | What to do |
|---|---|---|
Failed to download theme file. Please check your internet connection. |
The download failed | Check the network and try again |
Failed to install required files. Please check you've enough free space on your storage ! |
Writing or renaming failed | Free up space on SHARE and on the boot partition |
Unexpected error while retrieving theme list ! Please retry later. |
The catalogue could not be fetched | Check the Internet connection, then reopen the manager |
Themes distributed outside the official repository (an author's GitHub repo, a personal page, a Discord post…) are installed by copying their folder.
share/themes, reachable through the \\RECALBOX\share\themes network share, through the web manager, or directly on the SD card (SHARE/themes/) — see File management.THEME MANAGER (or press START if it is already open). No reboot needed.The tree must look like this — one folder per theme, with theme.xml at its root, and definitely not the theme files loose inside themes:
📁 recalbox
┣ 📁 share
┃ ┣ 📁 themes
┃ ┃ ┣ 📁 my-theme
┃ ┃ ┃ ┣ 🗒 theme.xml
┃ ┃ ┃ ┣ 📁 snes
┃ ┃ ┃ ┣ 📁 megadrive
Avoid spaces, accented and special characters in the theme folder name: theme settings are stored in
recalbox.confunder a key built from that name, and any character outsidea-z,A-Z,0-9,_,.and-is replaced with a dash.
A theme copied this way appears in the manager under the name read from its theme.xml, with author UNKNOWN if the file declares none, version UNKNOWN, and the description This a manually installed theme. We have no information about it.. You can apply it (A), delete it (X) and tune its options (Y) like any other theme.
This is what most often breaks a theme picked up elsewhere: a theme built for an older Recalbox will show missing systems, misplaced artwork, or refuse to load.
Compatibility is declared by the theme itself, in the <theme> tag of its theme.xml:
<theme name="My theme" version="1.0" recalbox="10.0" compatibility="hdmi,crt" resolutions="hd,fhd">
recalbox — the minimum Recalbox version. Below 9.2, Recalbox warns that The theme version is too old and the theme may not work properly. In practice, aim for a theme built for 10.x: the format changed a lot.compatibility — the supported display types: hdmi, crt, jamma, tate.resolutions — the supported resolutions: qvga (240p), vga (480p), hd (720p), fhd (1080p).Those same values feed the pictograms shown in the manager and the compatibility tick in the USER INTERFACE SETTINGS → THEME → THEME SET list. Themes from the built-in catalogue are tested against the installed version; those picked up elsewhere are not.
The full description of these attributes lives in the File tree page of the theme documentation.