Configuration overrides let you change the behavior of Recalbox, RetroArch or an emulator for a single game or for every game in a folder, by dropping simple text files inside your roms folders. In practice you can:
Override files live among your roms: they survive an update, a factory reset and even an SD card change if your roms are on external storage. They are portable too: copy your roms to a friend's box and your settings follow.
Each override type applies on top of a base configuration file, loaded when a game starts:
| Override suffix | Target | Base file |
|---|---|---|
.recalbox.conf |
Recalbox (emulator choice, launch options) | /recalbox/share/system/recalbox.conf |
.retroarch.cfg |
RetroArch (excluding core options) | /recalbox/share/system/configs/retroarch/retroarchcustom.cfg |
.core.cfg |
RetroArch core options | /recalbox/share/system/configs/retroarch/cores/retroarch-core-options.cfg |
All these files use the key=value format (one setting per line). An override can change the value of an existing key or define a new one.
A few standalone emulators also have their own dedicated override file — see the section at the bottom of this page.
The principle: Recalbox first loads the base configuration, then applies successively every override file found at each folder level, from the root down to the game's folder, and finally the game's own override if it exists. Each level can therefore override the previous one.
Example: when launching /recalbox/share/roms/snes/platform/Aladdin (France).zip, the RetroArch configuration is built in this order:
/recalbox/share/system/configs/retroarch/retroarchcustom.cfg/.retroarch.cfg/recalbox/.retroarch.cfg/recalbox/share/.retroarch.cfg/recalbox/share/roms/.retroarch.cfg/recalbox/share/roms/snes/.retroarch.cfg/recalbox/share/roms/snes/platform/.retroarch.cfg/recalbox/share/roms/snes/platform/Aladdin (France).zip.retroarch.cfgIn practice, place your overrides no higher than a system's folder (roms/snes/…).
Two naming rules to remember:
roms/snes/.retroarch.cfg applies to the whole snes folder.Aladdin (France).zip.retroarch.cfg..recalbox.conf)This is the most common use: forcing an emulator or core for a game or a folder, with the global.emulator / global.core keys (or their per-system variants <system>.emulator / <system>.core, which take precedence).
Example: my game /recalbox/share/roms/pcengine/1943 Kai (Japan).zip works better with the mednafen_pce_fast core than with the default one. I create the file /recalbox/share/roms/pcengine/1943 Kai (Japan).zip.recalbox.conf:
global.emulator=libretro
global.core=mednafen_pce_fast
The emulator is picked in this order (each step beats the previous one):
<system>.emulator / <system>.core in recalbox.conf;EDIT GAME — stored in gamelist.xml);.recalbox.conf override files (folders, then game).An override therefore takes precedence over the choice made in the menus — and unlike gamelist.xml, it cannot be lost to a bad scrape.
The core names to use are listed on each system's page in the Emulators section of this wiki.
To have several MAME romsets side by side, each in its own folder:
┣ 📁 roms
┃ ┣ 📁 mame
┃ ┃ ┣ 📁 romset-0.78
┃ ┃ ┣ 📁 romset-0.139
File /recalbox/share/roms/mame/romset-0.78/.recalbox.conf:
mame.emulator=libretro
mame.core=mame2003_plus
File /recalbox/share/roms/mame/romset-0.139/.recalbox.conf:
mame.emulator=libretro
mame.core=mame2010
Shortcut without any file: inside the
mamefolder, a subfolder with a known name (mame2000,mame2003,mame2003+,mame2010,mame2015,mame2016,mame0258,mame0278,advancemame…) automatically selects the matching core for everything it contains. The.recalbox.confoverride remains useful for arbitrary folder names — and still beats this automatic detection.
Beyond the emulator choice, the recalbox.conf keys read when a game is launched can be overridden, in their global.* or <system>.* flavor: ratio, smooth (bilinear filtering), rewind, autosave, integerscale, shaderset / shaders, showfps, hdmode, widescreenmode, recalboxoverlays, quitpresstwice, netplay, translate (and translate.from, translate.to…), runahead, reducelatency, rumble…
Example — disable smoothing and enable rewind for the whole snes folder: file /recalbox/share/roms/snes/.recalbox.conf:
global.smooth=0
global.rewind=1
These keys are detailed on the recalbox.conf page.
Overriding a key that is not read at game launch has no effect: don't expect to change EmulationStation's game list behavior (sorting, favorites…) this way. The
videomodekey (CEA x HDMImodes) only applies to Raspberry Pi 0, 1 and 2: on other machines, set the per-game resolution from the EmulationStation options.
.retroarch.cfg).retroarch.cfg files override RetroArch's configuration: video (ratio, rotation, shaders), audio, overlays, controllers and hotkeys, netplay, in-game translation, save directories… They obviously only apply to Libretro emulators (RetroArch cores).
These overrides are applied last at launch: they win over the configuration generated by Recalbox, including the overlay settings.
Example — some N64 games such as GoldenEye 007 or Perfect Dark require the "analog to digital" option to be disabled; file /recalbox/share/roms/n64/.retroarch.cfg:
input_player1_analog_dpad_mode = "0"
input_player2_analog_dpad_mode = "0"
➡️ List of useful keys: RetroArch overrides
.core.cfg)Each Libretro core has its own options (visible in the RetroArch menu, CORE OPTIONS). .core.cfg files let you pin them per folder or per game — ideal for multi-machine cores, where you can create one subfolder per model:
┣ 📁 roms
┃ ┣ 📁 thomson
┃ ┃ ┣ 🗒 .core.cfg
┃ ┃ ┣ 📁 MO5
┃ ┃ ┃ ┣ 🗒 .core.cfg
┃ ┃ ┣ 📁 TO8-TO9
┃ ┃ ┃ ┣ 🗒 .core.cfg
File /recalbox/share/roms/thomson/.core.cfg (shared settings — auto-detected machine, autorun, write protection):
theodore_rom = "Auto"
theodore_autorun = "enabled"
theodore_floppy_write_protect = "enabled"
theodore_tape_write_protect = "enabled"
File /recalbox/share/roms/thomson/MO5/.core.cfg:
theodore_rom = "MO5"
File /recalbox/share/roms/thomson/TO8-TO9/.core.cfg (the TO9+ is backward compatible with the whole TO8/TO9 series):
theodore_rom = "TO9+"
Each subfolder now emulates the right machine, without relying on auto-detection.
Since Recalbox 10.1, the PUAE core (Amiga) shows by default, when launching a WHDLoad game that supports it, a game configuration screen (option puae_use_whdload_prefs = "config"). To disable it for your whole Amiga folder, create for instance /recalbox/share/roms/amiga1200/.core.cfg:
puae_use_whdload_prefs = "disabled"
.core.cfgoverrides are merged into the globalretroarch-core-options.cfgfile, where RetroArch then saves them. If you override a game with a specific value, also pin the "normal" value in the folder's.core.cfg(for instancefbneo-frameskip = "0"in the folder and"2"for the game), otherwise the game's value will stick for the next games.
The options available for each core are listed on the core's page in the Emulators section of this wiki.
To polish your subfolders (MAME versions, Thomson machines…), you can replace the picture and description EmulationStation displays for a folder. Place inside the folder:
.folder.picture.png — the picture shown instead of the folder preview (a resolution close to your scraped images is recommended);.folder.description.txt — text displayed below the picture (optional).The description file may contain per-language sections, with an automatic fallback to [en] and then to the whole text:
[fr]
MAME 2003 Plus — romset basé sur MAME 0.78.
[en]
MAME 2003 Plus — romset based on MAME 0.78.
📷 Screenshot to come:
configuration-override-folder.png(folder with a custom picture and description in EmulationStation)
A few standalone emulators (outside RetroArch) have their own override file, with the same folders-then-game cascade:
| Emulator | Override suffix | Specificity |
|---|---|---|
| Hatari (Atari ST) | .hatari.cfg |
full cascade |
| Vice (Commodore) | .vice.conf |
full cascade |
| Amiberry (Amiga) | .uaeconfig.uae in the rom's folder, or <rom without extension>.uae next to the rom |
no cascade; .amiberry.conf additionally overrides the host configuration |
| XRoar (Dragon/CoCo) | .xroar.config |
only the file closest to the game is used (no merging) |
| VG5000 | .vg5000.cfg |
full cascade |
The other standalone emulators cannot be overridden: adding these mechanisms requires emulator-specific code and testing. Feel free to discuss a specific need on the Recalbox Discord.