Batocera 43.1 Download: Install in 12 Steps, 30 Min

There is a particular species of disappointment reserved for the person who flashes a retro-gaming distribution, boots it, and finds an empty shelf. Batocera earns that reaction more than most, because it is very good at everything except the one thing beginners assume it does: it ships no games. None. It also ships no BIOS files, no ROMs, and no apology for either. What it does ship - as of version 43.1 'Glasswing', released May 30, 2026 - is a read-only Linux operating system that boots straight into a controller-driven game launcher, carries north of 200 preconfigured emulators, and asks you to bring your own legally-obtained backups. This tutorial covers the download in full: choosing the right image, verifying it, flashing it in twelve steps, and the configuration nobody bothers to document.

We will be precise about versions, because the internet is not. At the time of writing there are three builds you might plausibly be told to download, and only one of them is current. We will also be precise about the traps - the 16 GB card that quietly disables updates, the architecture mismatch that produces a black screen, and the two or three 'setup guides' circulating in 2026 that were written by machines considerably less honest than this one.

What Batocera Actually Is (and Isn't)

A read-only OS that boots straight into a launcher

Batocera is a self-contained Linux distribution whose entire purpose is to disappear. You flash it to a card, it boots, and within seconds you are staring at EmulationStation - the same front end that RetroPie and Recalbox use - driven entirely by a controller. There is no desktop to log into, no package manager to babysit, no apt upgrade at two in the morning. The operating system itself lives on a small read-only partition; everything you personally touch (games, saves, scrapes, configuration) is written to a separate writable partition called SHARE. That separation is not cosmetic. It means a botched configuration cannot brick the OS, and an OS update cannot eat your saves. It also means that when a tutorial tells you to edit a system file, you will occasionally need to remount a partition read-write first - a detail we return to in the advanced section.

No games, no BIOS, no exceptions

This is the line that trips up newcomers, so read it twice: Batocera contains zero games and zero BIOS files. The project states this plainly, and it states it because the alternative is a lawsuit. Distributing a copyrighted PlayStation BIOS or a stack of SNES ROMs is exactly the kind of activity that gets a project's domain seized. So Batocera hands you an empty, immaculately organized filing cabinet and expects you to fill it with backups you are legally entitled to make - cartridges you own and dumped yourself, discs you ripped, homebrew you downloaded from its author. If you would rather produce your own legal cartridge dumps than trust a stranger's archive, our twelve-step Retrode cart-dumping walkthrough is the honest starting point.

How it differs from RetroPie and Recalbox

All three distributions wrap EmulationStation and libretro cores, so on a Raspberry Pi they can look nearly identical. The difference is scope. RetroPie is a Pi-first project layered on top of Raspberry Pi OS, and in 2026 it is effectively frozen - its last image sits at v4.8, a state of affairs we covered when we noted RetroPie stalling at v4.8 as the Pi marched on. It carries more GitHub stars than Batocera (roughly 10,381 to 3,084 as of June 2026), which tells you about history, not health. Recalbox is friendlier for absolute beginners but conservative about hardware. Batocera's distinguishing move is first-class x86_64 support: the same distribution that runs a Raspberry Pi 2 will drive a mini-PC through PS2, GameCube, and - on genuinely capable silicon - PS3. Batocera and Recalbox both ship an official Raspberry Pi 5 image; RetroPie does not. For a builder who wants one image across a shelf of very different machines, that breadth is the whole argument.

Glasswing, Papilio, and the 2026 Release Cadence

43.1 'Glasswing': the current stable

As of this writing the current stable build is Batocera 43.1, codenamed 'Glasswing', a point release published on May 30, 2026. It is a stability follow-up to 43.0 'Glasswing', the major version that landed three weeks earlier on May 8, 2026, built on Linux kernel 6.15.11. The 43 series widened hardware support considerably - new device profiles arrived for the AYN Thor, Odin 2 Mini, Powkiddy X55, the Retroid Pocket 6, and the Radxa Dragon Q6A, among others - and modernized the x86 graphics stack onto a Wayland compositor. The .1 exists precisely to fix what the major shipped slightly wrong: it repaired missing systems in EmulationStation, broken LR-Dolphin options, and the delightful bug where Microsoft controllers were detected as keyboards. If you are flashing a card today, 43.1 is the build you want.

42 'Papilio': the build before

The prior major cycle was Batocera 42, codenamed 'Papilio' (you will see it written 'Papilio Ulysses' in places), released on October 12, 2025. It is worth knowing the name for one practical reason: BIOS folder conventions occasionally shift between majors. The Dreamcast boot ROM, for instance, is expected at bios/dc/dc_boot.bin in the v42-and-later layout, and a guide written against an older tree will send you to the wrong directory. When a system stubbornly reports a missing BIOS despite a file that looks correct, version drift in the expected path is a prime suspect. Papilio also broadened handheld and light-gun support - the Anbernic RG351V, the Odin 2 and Odin 2 Portal, and open light-gun firmware like OpenFIRE all arrived in that cycle.

Why a fast cadence is the point

Batocera ships new majors on a roughly seasonal rhythm and slots point releases in between, which is a meaningful contrast with a project frozen for years. Fresher builds mean fresher libretro cores, and fresher cores mean fixes for emulators that were, until recently, unplayable - N64 accuracy, PS2 performance on x86, Saturn timing. You will see this framed elsewhere in 2026 as Batocera simply updating 'more often' than RetroPie; treat the specific comparison sites making that claim with suspicion, because several are AI content farms with fabricated bylines, but the underlying observation is correct and verifiable from the project's own changelog. The lesson for a downloader is boring and important: pull the newest stable, not whatever a two-year-old forum post links.

Prerequisites: Hardware, Cards, and Software Versions

Supported hardware

Batocera 43.1 runs on a deliberately wide spread of machines. On the Raspberry Pi side it covers the Pi 2, 3, 4/400, and 5, with an official Raspberry Pi 5 image in the 2026 line. On the PC side it targets x86_64 desktops, laptops, and mini-PCs, which is also the image Steam Deck owners use. And then there is the long tail of ARM handhelds - Rockchip RK3588 units, Allwinner H700 boards like the Anbernic RG35XX family, and dozens of others. The floor is modest: 1 GB of RAM is the minimum, 2 GB is comfortable, and the rest is storage and patience. If you are shopping for one of those handhelds specifically to run this software, our comparison of the Retroid Pocket 6 versus the 5 covers the current price-to-performance picture, and the Miyoo Mini Plus ROM situation is a useful reality check on the 'thousands of games included' marketing that these devices attract.

The 32 GB card rule

Here is the single most consequential prerequisite, and the one most guides get wrong: for the 2026 v43 series you want a card or USB drive of at least 32 GB. The technical minimum is still 16 GB and Batocera will boot from it - but it cannot download automatic updates on a 16 GB drive, because there is no room to stage the new image alongside the old one. So 32 GB is the practical floor, not a suggestion. Buy a reputable card (SanDisk, Samsung); the counterfeit and cut-rate cards that plague marketplaces will pass a quick format and then corrupt your userdata a week later. A 64 GB A1 or A2-rated card is the sane default and costs almost nothing.

Flashing software and versions

You need exactly one flashing tool. The project recommends three, and any of them works: balenaEtcher, the Raspberry Pi Imager, or USBImager. Etcher is the most foolproof for beginners because it validates the write and hides the raw device path; the Raspberry Pi Imager is the natural choice if you are already in the Pi ecosystem; USBImager is a tiny, no-nonsense option for people who distrust Electron apps. All three decompress Batocera's .img.gz images on the fly, so you do not need to unzip anything first. Linux and macOS users who prefer the command line can use dd directly, which we show below with the appropriate warnings. Whatever you pick, grab the current version from the vendor - an ancient Etcher build occasionally chokes on modern high-capacity cards.

Choosing the Right Image for Your Architecture

Reading the o2switch mirror

Batocera's images are hosted at the project's mirror, and understanding its layout saves you from the number-one flashing mistake. The mirror is a plain directory tree, one folder per architecture, and each architecture folder contains a /stable/last/ path that always points at the newest build. It looks roughly like this:

https://mirrors.o2switch.fr/batocera/
  x86_64/     -> PCs, mini-PCs, Steam Deck, most x86 handhelds
  bcm2712/    -> Raspberry Pi 5
  bcm2711/    -> Raspberry Pi 4 / 400
  bcm2837/    -> Raspberry Pi 3
  bcm2836/    -> Raspberry Pi 2
  rk3588/     -> many Rockchip ARM handhelds (Powkiddy, some Retroid)
  h700/       -> Allwinner handhelds (Anbernic RG35XX line)

Each arch folder contains:  /stable/last/   (the newest build)

Download the image from the folder that matches your device, and only that folder. There is no universal image; a build compiled for the Raspberry Pi 5's Broadcom SoC will not boot on a PC, and vice versa.

x86_64 versus the Raspberry Pi codes

The confusing part is that Batocera names Raspberry Pi images after the Broadcom chip, not the Pi's marketing number. The Pi 5 is bcm2712; the Pi 4 and 400 are bcm2711; the Pi 3 is bcm2837; the Pi 2 is bcm2836. Grab bcm2711 because you saw 'Pi' and own a Pi 5, and you will get a black or rainbow screen and no explanation. PCs, mini-PCs, and Steam Decks all take the single x86_64 image. ARM handhelds are their own adventure: many Rockchip units use rk3588, the RG35XX-class Allwinner devices use h700, and the safest move is to check the supported-devices list rather than guess.

Finding your board's arch string

If you already have Batocera running on a device and want to be certain which architecture it is - essential before an SSH upgrade - ask the system directly. The board string is written to a file at boot, and printing it removes all ambiguity:

# From a running Batocera device (F1 file manager terminal, or SSH):
cat /boot/boot/batocera.board

# Example output on a Raspberry Pi 5:
bcm2712

# Example output on a generic PC or mini-PC:
x86_64

That value is exactly the folder name you want on the mirror. Copying an x86_64 upgrade URL onto a Raspberry Pi is one of the most common self-inflicted wounds in the Batocera support channels, and this one command prevents it.

Downloading and Verifying the Image

Official site or mirror

There are two legitimate places to get the image. The official website, batocera.org, hosts a download section that walks you through picking a device and hands you the correct file - the friendliest route for a first-timer. The o2switch mirror we just dissected is faster and more complete: it exposes every architecture and, critically, older builds, which matters when a brand-new release regresses on your specific hardware and you need to pin the previous one. Both serve the same files. Ignore any third-party site offering a 'modified' or 'preloaded' Batocera image; at best it is stale, at worst it is a felony wrapped in a disk image.

Verifying and decompressing

The compressed image is roughly 3 GB and decompresses to about 8 GB on the card. A download is worthless if it arrived corrupted, and a corrupted image flashes a card that boots to nothing. If the mirror lists a checksum next to the file, verify it before you flash. On Linux or macOS you can also skip the flashing GUI entirely and write the compressed image straight to the card with dd, which is faster but unforgiving:

# If the mirror lists a checksum next to the image, verify it first:
sha256sum batocera-x86_64-43-20260530.img.gz

# Flash straight from the gzip - no need to decompress first (~3 GB in):
zcat batocera-x86_64-43-20260530.img.gz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync

# dd writes to whatever /dev/sdX names. Choose the wrong letter
# and you overwrite your system disk. Confirm the target with: lsblk

The comment in that block is not decoration. dd is nicknamed 'disk destroyer' for cause: it writes to whatever device node you name, and if you fat-finger /dev/sda when you meant /dev/sdb, it will cheerfully overwrite the operating system you are typing on. Run lsblk first, confirm the size matches your card, then proceed.

What the filename tells you

Batocera images follow a rigid naming pattern: batocera-(arch)-(version)-(date).img.gz. So batocera-x86_64-43-20260530.img.gz is the x86_64 build, major version 43, dated the 30th of May 2026 - which is to say, 43.1. The date is the real discriminator between a major and its point release, so when someone insists they are on '43' but hitting a bug that 43.1 fixed, the date in their filename settles the argument. Keep the file; if a future update misbehaves, having the exact image you started from is the fastest road back.

Flashing the Image in 12 Steps

The twelve steps

What follows is the complete flash-and-first-boot procedure. Done in order, on decent hardware, it takes roughly thirty minutes, most of which is the card write and the first-boot expansion. Each step includes the reason it exists, because 'the guide said so' is how people end up with black screens.

1. Confirm your device architecture. Match the image to the exact board from the previous section. Rationale: the single most common failure is flashing the wrong arch, which produces a device that powers on and displays nothing.
2. Download the matching image from batocera.org or the o2switch mirror. Rationale: the mirror also lists older builds, so bookmark it for the day you need to roll back a regression.
3. Verify the checksum if one is published. Rationale: a truncated or corrupted download flashes a card that boots to a blinking cursor, and you will wrongly blame the hardware.
4. Get a 32 GB or larger card and insert it. Rationale: 16 GB boots but silently disables automatic updates; anything smaller is a false economy.
5. Identify the card's drive letter or device node with your OS disk tool or lsblk. Rationale: you are about to erase this device entirely, so you must be certain which one it is.
6. Open your flashing tool (balenaEtcher, Raspberry Pi Imager, or USBImager) and choose the flash-from-file option. Rationale: these tools decompress the .img.gz for you and verify the write afterward.
7. Select the downloaded image. Rationale: pointing the tool at the still-compressed .gz is correct - do not waste time unzipping it manually.
8. Select the target card, carefully. Rationale: Etcher hides system disks by default, but dd and some imagers do not; a misselect here overwrites your PC.
9. Flash and let it verify. Rationale: the verify pass catches bad blocks on a failing card before you have wasted an evening loading ROMs onto it.
10. Move the card to the target device and power on. Rationale: first boot triggers the automatic partition expansion, which must happen on the real hardware, not in the imager.
11. Wait out the SHARE partition expansion without powering off. Rationale: Batocera grows the userdata partition to fill the card on first boot, and interrupting that write corrupts it - a reflash is your only recovery.
12. Map your controller, then set language, Wi-Fi, and check for updates. Rationale: everything downstream is controller-driven, and pulling updates immediately lands you on the latest 43.1 fixes before you invest hours in configuration.

First boot and partition expansion

The first boot is slower than every subsequent boot, and that is by design. A freshly flashed card carries a small BATOCERA boot partition and a SHARE partition sized to the image rather than the card. On first power-up, Batocera expands SHARE to consume all the unallocated space - a process the official installation wiki warns 'could take a few seconds or a few minutes' depending on card size and speed. The screen may sit on a logo or a console spew during this. Do not touch the power. When it finishes, EmulationStation appears and the writable space is yours.

Expected output

If you want to confirm the expansion actually happened, drop to a terminal after first boot and inspect the userdata mount. You should see the partition now reporting close to the full card capacity rather than the image's original size:

# Before first boot (freshly flashed 64 GB card):
# /dev/sda2   1.5G  1.2G   0.3G  80%  /userdata

# After first boot auto-expands the SHARE partition:
# /dev/sda2    58G  1.2G    57G   3%  /userdata

Numbers near your card's rated capacity mean the expansion succeeded. A userdata partition still stuck at one or two gigabytes on a 64 GB card means the first boot was interrupted, and the fix is to reflash and let it finish undisturbed.

First Boot: Controllers, Wi-Fi, and the SHARE Partition

Mapping a controller

The first time EmulationStation starts, it asks you to hold a button to begin controller mapping. Do it deliberately - this map is how you navigate everything from here forward, and a sloppy assignment (a D-pad direction skipped, the hotkey left unbound) will strand you in menus with no keyboard attached. Batocera recognizes the usual suspects out of the box: Xbox pads, DualSense and DualShock, 8BitDo controllers, and the built-in inputs on handhelds. Pay particular attention to the 'hotkey' button, usually mapped to Select or a Guide button; combined with Start it exits a game, and combined with other buttons it saves states, opens the in-game menu, and more. If a pad refuses to register, some 8BitDo units need to be powered on in a specific pairing mode - a firmware quirk, not a Batocera bug.

Wi-Fi and locale

Out of the box the interface is English; change the language and keyboard layout under the system settings if that is wrong, because the layout affects on-screen text entry for things like Wi-Fi passwords. Networking can be wired (plug in Ethernet and it simply works) or wireless (enter your SSID and key in the network menu). Wireless has one recurring gotcha: some single-board computers dislike 5 GHz networks or specific regulatory regions, and the cure is usually to point them at a 2.4 GHz SSID. Every one of these settings is also expressible as a plain line in the main configuration file, which is the approach we favor for repeatable builds and cover at the end.

The SHARE partition

Once Batocera is on the network, the SHARE partition becomes reachable from another computer, and this is by far the most comfortable way to load games. SHARE maps internally to /userdata and is exposed as a network share:

# Windows / macOS (SMB) - drop ROMs and BIOS here:
\\BATOCERA\share\roms\snes\
\\BATOCERA\share\bios\dc\dc_boot.bin

# Linux:
smb://BATOCERA.local/share/

# By IP if name resolution fails:
\\192.168.1.50\share

# SHARE maps internally to /userdata

On Windows, type the first path into Explorer's address bar; on macOS or Linux, connect to the smb address. You will see the familiar folder structure - roms, bios, saves, system - and you can drag files straight in over the network. No card-shuffling, no adapter, no re-flashing. This is also where the read-only OS design pays off: you are writing to SHARE, never to the operating system.

Adding Your Own Games and BIOS Files

Where ROMs go

Every system has a folder under /userdata/roms/, named for the platform's short name: /userdata/roms/snes/, /userdata/roms/genesis/, /userdata/roms/psx/, and so on. Each of those folders contains an _info.txt that lists exactly which file extensions that system accepts - read it when a game refuses to appear. Drop a game into the correct folder, then refresh the library via START then GAME SETTINGS then UPDATE GAMELISTS (or reboot). The most common 'no games found' complaint traces to files landing in the wrong place - often on the small BATOCERA boot partition instead of SHARE, or in a folder whose name does not match Batocera's expected system identifier. When in doubt, load over the network share, which drops you into the right tree automatically, and consult the project's systems reference for the exact folder name.

BIOS placement and md5 checks

Some systems will not launch without a BIOS - PlayStation, Saturn, and Dreamcast are the usual gatekeepers - and Batocera keeps these in /userdata/bios/, occasionally in a subfolder. The Dreamcast boot ROM, as noted, belongs at /userdata/bios/dc/dc_boot.bin in the current layout. Batocera includes a BIOS checker in its menus that lists every expected file, its target path, and the md5 hash it should match; run it after adding files. A BIOS with the right name but the wrong hash - a bad dump, a region mismatch, a 'patched' version from a sketchy pack - will fail silently or crash the emulator, and the md5 check is how you catch it before it wastes an hour.

Legal backups you dumped yourself

The uncomfortable part, stated without euphemism: the games and BIOS files are your responsibility, and the law in most jurisdictions permits format-shifting only from originals you own. The clean path is to dump your own cartridges and rip your own discs. It is more work than downloading a pack, and it is also the only version of this hobby that survives contact with a lawyer. Hardware dumpers make it tractable - our Retrode dumping guide walks a cartridge to a clean ROM and its save file in about thirty minutes, and the resulting files drop straight into the folders above. Batocera supplies the shelf; you supply the provably-yours contents.

Updating: In-App vs. batocera-upgrade over SSH

The in-app updater

For most people, updating never needs a terminal. From EmulationStation, open the main menu and navigate to UPDATES AND DOWNLOADS, then START UPDATE. Batocera checks the mirror, downloads the newest build for your architecture, and applies it on the next reboot - bug-fix point releases and whole version jumps alike, with your ROMs, saves, and scrapes untouched. This is the intended path, and it is the reason the 32 GB card requirement exists: the updater needs room to stage the incoming image beside the running one. On a 16 GB card this menu will refuse or fail, which is the tell that your card is too small.

batocera-upgrade over SSH

The manual route exists for control freaks and headless machines, and it has been the recommended CLI method since Batocera 5.23 - which, yes, includes the entire 2026 v43 series - as documented in the manual upgrade guide. Enable SSH (it is on by default on most images), connect, and confirm what you are running first:

# Default login (change this password on any networked machine):
ssh root@batocera        # or:  ssh root@192.168.1.50
# password:  linux

# Version, board, kernel, and free space:
batocera-info
df -h /userdata

Then point batocera-upgrade at the correct architecture's latest-stable URL. Note the full path - it includes /batocera/, which a surprising number of copied-and-pasted commands omit:

# Upgrade in place. ROMs, saves, scraped metadata and configs are kept.
batocera-upgrade https://mirrors.o2switch.fr/batocera/x86_64/stable/last

# ---- expected tail of output ----
# Download: 100%
# The system will be upgraded on the next reboot.
reboot

The command downloads the new system image, stages it, and applies it on reboot without touching userdata. The one rule: the URL's architecture must match the machine. Paste an x86_64 URL onto a Raspberry Pi and the upgrade will refuse or, worse, half-apply; derive the right arch from batocera.board first, every time.

Stable versus beta

Batocera runs two update channels. Stable is the default and the correct choice for a machine you actually want to use - it is what 43.1 is. The bleeding-edge channel is beta, selected in the update settings or by setting updates.type=beta in the configuration file, and it carries the newest cores and the newest regressions in equal measure. Unless you are testing a specific fix or reporting bugs, stay on stable; beta is for people who enjoy the update itself as a hobby, separate from playing games.

Troubleshooting: Pitfalls and Fixes

Five pitfalls that cost the most time

Most Batocera 'problems' are one of a handful of self-inflicted wounds. In rough order of how often they burn an evening:

• The 16 GB card that kills updates. Everything works except UPDATES AND DOWNLOADS, which fails or greys out. Fix: reflash to a 32 GB or larger card. There is no software workaround; the space simply is not there.
• The wrong architecture. The device powers on to a black or rainbow screen and never reaches EmulationStation. Fix: reflash the image whose name matches your batocera.board string exactly - bcm2712 for a Pi 5, not bcm2711.
• Powering off during first-boot expansion. Interrupting the SHARE resize corrupts userdata, and the symptoms are bizarre and intermittent. Fix: reflash and, this time, wait for EmulationStation to appear before touching anything.
• Expecting included games. The system list is short or the 'recently added' shelf is empty because you assumed content ships with the OS. Fix: add your own ROMs to /userdata/roms/; there is nothing to 'unlock'.
• ROMs in the wrong place. Files dumped onto the tiny boot partition, or into a mis-named folder, never appear. Fix: load over the SHARE network share and use the exact folder names from the systems reference.

The troubleshooting table

A denser quick-reference for the failures above and the ones that tend to follow them:

When to just reflash

Batocera's read-only design means the operating system rarely rots, but a card can. If you are chasing an intermittent, escalating set of symptoms - corrupt saves, systems vanishing, a UI that freezes at random - stop debugging and suspect the storage. Copy your /userdata off over the network, run a card-health check (H2testw or f3 will expose a counterfeit's fake capacity), and if it is genuine, reflash and copy userdata back. Because your games and configuration live on SHARE, a full reflash costs you nothing but the write time, and it resolves a startling share of 'bugs' that were really a dying microSD all along.

Advanced Tips: Overrides, Bezels, and the Read-Only OS

Editing batocera.conf directly

Every setting you can reach through EmulationStation's menus is ultimately a line in one file: /userdata/system/batocera.conf. The GUI writes to it; you can too. For a build you intend to reproduce - a second machine, a rebuild after a card failure - editing this file directly is faster and version-controllable in a way that clicking through menus never is. Edit it over the SHARE network share or via SSH. One caveat rooted in the read-only design: /userdata is writable, so batocera.conf edits stick immediately, but if a tip ever tells you to edit something on the boot partition (an overclock line, say), that partition is mounted read-only and you must remount it first with mount -o remount,rw /boot, edit, then remount read-only or reboot.

Per-system and per-game overrides

batocera.conf uses a simple prefix convention that lets a setting cascade or override. A key beginning global. applies everywhere; a key beginning with a system's short name overrides it for just that system. This is how you pin a better core for one platform without disturbing the rest:

# /userdata/system/batocera.conf  ->  cascading overrides

# global.* applies to every system:
global.smooth=0
global.rewind=1
global.shaderset=none

# SNES: pin a specific libretro core
snes.core=snes9x

# N64: mupen64plus-next regressed on ARM, so pin Parallel N64
n64.core=parallel_n64

# PS2: LRPS2 is x86_64 only - do NOT set this on a Raspberry Pi
ps2.core=lrps2

Those core choices are not arbitrary. Parallel N64 is the pragmatic pick on ARM after mupen64plus-next regressed, and LRPS2 is x86_64-only, so setting it on a Raspberry Pi buys you nothing but a broken PS2 entry - the kind of detail that separates a working build from a plausible-looking one. Per-game overrides go one level finer: open a game's options from the in-game menu and Batocera writes a game-specific override without your ever editing a file, which is the right tool for the one title that needs a quirk the rest of the system does not.

Shaders, bezels, and RetroAchievements

Three finishing touches earn their keep. Shaders - set global.shaderset to a preset like scanlines - reintroduce the CRT look that pixel art was drawn for, at a GPU cost you can afford on x86 and should budget carefully on a Pi. Bezels, controlled by global.bezel, fill the black bars beside a 4:3 game with artwork instead of void. And RetroAchievements bolts an achievement layer onto retro titles: set global.retroachievements to 1 and supply your account name, and the emulator awards trophies against the community's database. None of these change what runs; they change how it feels, which after the twentieth hour is not nothing. For the core-by-core specifics of what each emulator's options do, the libretro documentation is the authority.

A Complete Working batocera.conf

The full file

Here is a complete, sane baseline for /userdata/system/batocera.conf on Batocera 43.1. It sets locale and networking, keeps updates on the stable channel, establishes reasonable global emulator defaults, and pins a few known-good cores. Replace the Wi-Fi and timezone values with your own, and treat the RetroAchievements block as optional:

############################################
#  /userdata/system/batocera.conf
#  Batocera 43.1 'Glasswing' - working base config
############################################

## --- System / locale ---
system.language=en_US
system.timezone=America/New_York
system.hostname=BATOCERA

## --- Network / Wi-Fi ---
wifi.enabled=1
wifi.ssid=YourNetworkName
wifi.key=YourNetworkPassword     # becomes enc:xxxx after first reboot

## --- Updates ---
updates.type=stable              # set to 'beta' for the bleeding-edge channel

## --- Audio ---
audio.volume=90

## --- Controllers ---
controllers.bluetooth.enabled=1

## --- Global emulator defaults ---
global.smooth=0
global.integerscale=1
global.rewind=1
global.shaderset=none
global.bezel=default

## --- RetroAchievements (optional) ---
global.retroachievements=0
global.retroachievements.username=

## --- Per-system core overrides ---
snes.core=snes9x
n64.core=parallel_n64
psx.core=swanstation
ps2.core=lrps2

What each block does

The system block sets language, timezone, and hostname - the hostname is what you type after the double backslash to reach the network share. The Wi-Fi block is self-explanatory, except for one nicety: after the first reboot Batocera rewrites your plaintext wifi.key as an encrypted enc: string, so do not be alarmed when the password you typed disappears (and if it contains special characters, escape them with a backslash). updates.type=stable keeps you on the channel 43.1 lives on. The global block sets defaults every system inherits: no bilinear smoothing (crisp pixels), integer scaling on, rewind enabled, no shader by default, and bezels on. The RetroAchievements block is dormant until you flip it to 1 and add a username. The per-system lines at the bottom override cores for four platforms where the default is not always the best choice.

Applying it and making it stick

Drop the file into /userdata/system/, overwriting the existing one, then reboot - Batocera reads it at startup. Two warnings save grief. First, this file is a merge, not a monolith: the running system holds many more keys than shown here, and if you paste a partial file expecting it to be exhaustive, unlisted settings simply keep their prior values rather than resetting. Second, remember that the EmulationStation menus write back to this same file, so a setting you change in the GUI after the fact will edit or append here - the file and the menus are two views of one truth. Keep a copy of your finished batocera.conf alongside the image you flashed, and rebuilding this machine after a card death becomes a five-minute copy job rather than an evening of re-clicking.