Batocera.linux is based on buildroot. You can see buildroot as a minimal Linux distribution while it maintains base packages. However, it's a tool to build root file systems (like a firmware). Batocera.linux mainly includes extra packages not available on buildroot (emulators, front-end, additional drivers for devices…) and configuration.

More information about buildroot can be found here :

Technically, batocera.linux has 2 partitions. 1 for the system, 1 for the user data. The partition named BATOCERA visible on any computer under Windows, MacOS or Linux is the system. It is a partition formatted in FAT32, which is kind of a universal format, supported by almost every OS, and boot system (BIOS or UEFI).

It contains mainly 3 files :

  • linux, the technical system (about 10 MB)
  • batocera, the software system containing all the programs (about 1.1GB compressed)
  • initrd.gz or uInitrd, the loader (about 600 kB)

Upgrading the system means mainly that these 3 files are getting upgraded. There are some other files depending on the architecture.

The file batocera can be seen like a firmware, you cannot modify it. However the architecture is a bit more complex and allows you to modify the firmware without recompiling everything : batocera.linux supports and uses by default overlayfs. The real system is the firmware (the file batocera) + a filesystem in memory initialized with the file overlay if it exists. The overlay is an in-memory filesystem and not directly the overlay file because under linux, you cannot properly unmount the root filesystem, mainly when it's a complex root from several filesystems.

As a general rule, the file overlay doesn't exist, unless it's created by the script batocera-save-overlay if a user or developer customizes the system.

| TMPFS, writable                | --> must be saved explicitly on /boot/overlay
| firmware (squashfs), read only |

More details on overlayfs can be found here :

When you create the card to run batocera.linux, the card is more complex than a basic card, and it's dependent on the architecture. It's why you need a special tool to burn it.

  • BEFORE BOOT : these are technical files to be able to access the BOOT partition and run the Linux kernel.
  • BOOT : this partition is visible on Windows. This is where the batocera.linux system is.
  • FREE : this free space is filled with a SHARE partition on the first boot to save all the user data (ROMs and ancillary files like screenshots, video snaps and so on).
  • SHARE : this partition replaces FREE at the first boot. It is partitioned as EXT4 by default, but you have other options depending on the usual OS you have on your other computers. See the chapter “Userdata file systems” below.


      1                  1263
| MBR |                   |  BOOT  |     FREE     |
     512                 631K


      1                  1263
| MBR | GRUB              |  BOOT  |     FREE     |
     512                 631K


      1      31      63          719     1231    1263
| MBR |  bl1  |  bl2  |   uboot   |  tzsw  |       |   BOOT   |     FREE     |
     512     15K     31K         359K     615K    631K       1.2G


      1       97         1281
| MBR |  bl1  |   uboot   |  BOOT  |     FREE     |
     512     48K         640K

This is an important question: what is the best file system to choose to host your user data (ROMs and ancilliary metadata).

Here are a few guidelines:

  • If your own other Linux systems, you're probably comfortable with ext4 and it's still one of the best options.
  • Btrfs is a newer option, if you have Windows machines, Batocera comes with the driver embedded. No restriction when using Btrfs, but you can't read it natively with MacOS.
  • NTFS is an OK option - it provides the ability to use your userdata drive with Windows, MacOS and most Linux distributions.
  • FAT32 and extFAT are outdated filesystems. Yes, they are well supported under any Operating System (you bet, those file systems are 40 year old!) but they have restrictions in terms of maximum file size (especially for newer console systems with ROMs sizes that can exceed 4GB!) or the ability to support the exec bit to run Linux applications. It will also limit the use of certain emulators and systems that rely on features like symbolic links or special character filename handling, that are not possible with FAT32 and ExtFat: Amiga or Wine/Windows are popular systems that won't work well with those filesystems on /userdata.

How can you format a disk in Btrfs (or ext4, or exFAT)? Batocera can do it for you, in SYSTEM SETTINGS –> DEVELOPER –> FORMAT A DISK. Of course, when you format a partition, you lose everything that was on it. So, backup your ROMs and user data before doing this!

  • batocera.linux_architecture.txt
  • Last modified: 9 months ago
  • by lbrpdx