The Recalbox boot partition (/boot, shown as RECALBOX when you insert the card into a computer) holds the files read before the system starts. This is where low-level display settings, overclocking, hardware overlays and storage detection are configured.
These settings only apply to the Raspberry Pi and handheld consoles, except
recalbox-boot.conf, which applies to every machine including PCs.
| File | Purpose | Editable? |
|---|---|---|
recalbox-user-config.txt |
Your low-level Raspberry Pi settings: video mode, overlays (dtoverlay=), parameters (dtparam=), overscan… |
✅ This is where you write |
recalbox-boot.conf |
Where to find the SHARE partition, network mounts, storage wait time |
✅ Yes |
config.txt |
Recalbox's own boot configuration | ❌ No — overwritten at every update |
recalbox-oc-config.txt |
Overclocking settings | ❌ No — managed by the ADVANCED SETTINGS → OVERCLOCK menu |
cmdline.txt |
Parameters passed to the Linux kernel | ❌ No, unless support explicitly tells you to |
Never add anything to
config.txt. That file is regenerated at every Recalbox update: your additions would vanish. Its last line loadsrecalbox-user-config.txt, whose contents override everything else — so that is the right place for your settings, and they survive updates.
recalbox-user-config.txtRECALBOX partition appears.recalbox-user-config.txt with a plain text editor (Notepad, Notepad++, TextEdit, nano…).If the
RECALBOXpartition does not show up, see The "SHARE" partition does not show up in Windows — the same procedure applies.
Connect over SSH.
Make the boot partition writable:
mount -o remount,rw /boot
Edit the file:
nano /boot/recalbox-user-config.txt
Save (Ctrl+X, Y, Enter) then reboot with reboot.
The file shipped with Recalbox already contains commented examples. A few common uses:
# Force a VGA video mode on an old screen
#hdmi_group=1
#hdmi_mode=1
# Force sound over HDMI (2) or DVI (1)
#hdmi_drive=2
# PAL composite output
#sdtv_mode=2
# No picture over HDMI: "safe" mode
#hdmi_safe=1
# Cheap TV with a garbled or slow picture
#hdmi_ignore_edid=0xa5000080
# Raspberry Pi 5: switch the M.2 port to PCI Express 3
dtparam=pciex1_gen=3
Remove the # in front of a line to enable it. The syntax is the Raspberry Pi config.txt syntax: the official documentation is the reference.
A mistake in this file can prevent the machine from booting or displaying anything. Keep a copy of the original version on your computer before changing anything.
recalbox-boot.confThis file tells Recalbox where to find your data, before the system even starts. The most useful options:
# Where the SHARE partition is:
# INTERNAL -> the partition following /boot on the same device (default)
# ANYEXTERNAL -> any device other than the boot one
# DEV <FSUUID> -> the device with this exact identifier
# NETWORK -> a network share (see sharenetwork_* below)
# RAM -> an in-memory disk (at your own risk)
sharedevice=ANYEXTERNAL
# Maximum time to wait for the storage, in seconds
# (useful for slow USB drives or network mounts)
sharewait=30
# Simple network mount (NFS or SMB)
sharenetwork_smb=SHARE@192.168.0.1:Documents/recalbox:guest
sharenetwork_nfs=ROMS@192.168.0.1:/Documents/recalbox/roms
Lines starting with ; or # are comments: remove the character to enable the option.
The
sharenetwork_*keys also accept a full command throughsharenetwork_cmd=. This is no longer needed to mount a USB, SATA or NVMe drive: since Recalbox 10, those devices are detected and mounted automatically — see Using an NVMe SSD as storage.
On x86_64 machines there is no config.txt and no recalbox-user-config.txt: those files are Raspberry Pi specific. Only recalbox-boot.conf is present and usable. Display settings are configured from the interface (START → ADVANCED SETTINGS → RESOLUTIONS).