Recalbox has a configuration file named recalbox.conf which lets you change options that are not all available in the interface.
To edit it, you can use:
system share (\\RECALBOX\system\recalbox.conf) — see File management;/recalbox/share/system/recalbox.conf;
- A
;at the beginning of a line means the line is disabled. Remove the;to enable the option. - Restart the Recalbox (or at least the interface) for a change to be taken into account. - Windows users: use a real text editor such as Notepad++ — Notepad can corrupt the file.
The factory file is organized in sections:
| Section | Contents |
|---|---|
| A — System Options | Boot video, dark mode, web manager, EmulationStation behavior, scraper, special keys, Kodi. |
| B — Network | Hostname, Wi-Fi (up to 3 networks), Samba, virtual gamepads, SSH. |
| C — Audio | Audio output, system and music volumes. |
| D — Controllers | Bluetooth, PS3 controllers, GPIO, DB9, gamecon, XArcade, Joy-Con, infrared, Wiimotes (Dolphin). |
| E — Language and keyboard | Language, keyboard, timezone. |
| F — Updates | Updates (enabling and channel). |
| G — Global emulator configuration | Settings applied to all emulators. |
| H — Emulators choices | Per-system settings (they override section G). |
| I/J — Netplay | Online gaming. |
The exact content varies slightly per machine (Raspberry Pis additionally have system.power.switch, the secondary TFT screen, Hyperion…; PCs have the external screen options). The 10.1 factory files can be browsed on GitLab: rpi3, rpi4_64, rpi5_64, rpizero2, x86_64, odroidgo2, rg353x. A pristine copy is also kept on your Recalbox: /recalbox/share_init/system/recalbox.conf.
These values apply to all emulators, unless overridden per system (see below).
| Key | Role | Values |
|---|---|---|
global.videomode |
In-game resolution | default (recommended), or a resolution 1920x1080… |
global.shaderset |
Automatic shader set | none, crtcurved, scanlines, retro — see Shaders configuration |
global.shaders |
Path to a specific shader (.glslp) |
e.g. /recalbox/share_init/shaders/scanline.glslp |
global.integerscale |
Pixel perfect (cropped image) | 0 / 1 |
global.ratio |
Aspect ratio | auto, 4/3, 16/9, 16/10, custom… |
global.smooth |
Image smoothing | 0 / 1 (default 1) |
global.rewind |
In-game rewind | 0 / 1 (default 1) |
global.autosave |
Auto save/load when quitting/launching a game | 0 / 1 |
global.retroachievements |
RetroAchievements | 0 / 1 + .hardcore, .username, .password, .sounds (10.1) |
global.inputdriver |
RetroArch input driver | auto (recommended), udev, sdl2 |
global.demo.systemlist |
Systems used by the "demo" screensaver | system list + .duration, .infoscreenduration |
global.translate |
In-game AI translation | 0 / 1 + .from, .to, .apikey, .url |
global.netplay.active |
Netplay | 0 / 1 + .nickname, .port, .relay, .lobby |
global.softpatching |
Softpatching | disable, auto, launchLast, select |
global.quitpresstwice |
Confirm HK+START to quit |
0 / 1 |
global.hdmode, global.widescreenmode |
HD and widescreen modes | 0 / 1 |
global.showfps |
Show FPS in game | 0 / 1 |
global.recalboxoverlays |
Recalbox overlays | 0 / 1 (default 1) |
Every system can override the global values: replace global. with the name of the system's rom folder. Examples:
snes.ratio=4/3
snes.rewind=0
n64.videomode=640x480
Three extra keys are system-specific:
<system>.emulator and <system>.core: force the emulator and core used (e.g. neogeo.emulator=libretro + neogeo.core=fbneo, the factory values). The emulators and cores available for each system are listed at the bottom of each system's wiki page (Emulators section);<system>.ignore=1: hide a system entirely;<system>.configfile: load your own configuration file — Recalbox then generates nothing for that emulator (advanced users).A few keys that have no menu entry in the interface:
| Key | Role | Default |
|---|---|---|
system.darkmode |
New in 10.1 — dims the boot splash (nice in a dark room) | 0 |
controllers.bluetooth.autopaironboot |
Automatic Bluetooth pairing at boot | 1 |
music.remoteplaylist.enable |
Remote interface music (Recalbox playlist, Jukebox) | 1 |
updates.type |
Update channel (stable by default; patron on Patreon builds — do not change this value by hand) |
stable |
patron.privatekey |
Patreon private key (filled through the PATRON menu) |
empty |
emulationstation.virtualkeyboard |
Virtual keyboard type: wheel, classic, simplified |
wheel |
autorun.enabled / autorun.path |
Boot straight into a specific game (arcade cabinets, dedicated consoles) | — |
wifi2.ssid / wifi2.key (and wifi3.*) |
Backup Wi-Fi networks (the first available one is used) | — |
system.emulators.specialkeys |
In-game HOTKEY shortcuts: default, nomenu, none — see Special commands |
default |
Some keys present in the factory file are leftovers with no effect in 10.1: this is the case of
emulationstation.videosnaps.*and of theemulationstation.arcade.*block (replaced by theemulationstation.virtualarcade*options, adjustable fromSYSTEM-LISTS & GAMELISTS SETTINGS,ARCADE SYSTEMSandARCADE GAMESsections). No point changing them.
| You want to… | Head to |
|---|---|
| Adjust these options without editing a file | The interface and the web manager |
| Configure shaders | Shaders configuration |
| Start over from a clean configuration | Reset to factory settings |