Batocera Download 2026: 43.1 in 12 Steps, 20 Min

Type batocera download into any search engine in 2026 and the first thing the machine tries to hand you is a beetle. Specifically Batocera, a genus of long-horned wood-boring insects that owns a perfectly respectable Wikipedia page and has precisely nothing to do with emulation, RetroArch, or the pile of Raspberry Pis fermenting in your desk drawer. That is pitfall number zero, and we have not downloaded a single byte yet.

The thing you actually want is Batocera.linux: a free, immutable, run-from-the-card operating system that turns a PC, a Raspberry Pi, or one of a dozen ARM handhelds into a console that boots straight into a game menu and asks nothing of you but a controller. As of this writing the official download page advertises version 43.1, last touched on 26 August 2026, under the four-word tagline "Download, flash, connect and play!" This guide is the long, load-bearing version of those four words: which file to grab, how to prove it arrived intact, how to write it without vaporizing your main drive, and what to do when the screen stays stubbornly black.

It is a twenty-minute job if nothing goes wrong, and about ninety if you skip the verification step and flash to the wrong disk. We are going to do it the twenty-minute way.

What Batocera Is (and the Beetle Problem)

Before you download anything, it helps to know what class of software you are dealing with, because it dictates every decision downstream. Batocera is not an application you install onto an existing operating system. It is the operating system. You write it to a card or a drive, you boot the machine from that card, and the whole thing runs there, read-mostly, with your games and saves quarantined on a separate writable partition.

The one-line pitch

Batocera.linux is a purpose-built Linux distribution whose entire job is to boot into EmulationStation (the menu you scroll with a d-pad) and hand your button presses to a stack of emulators, most of them libretro cores running under the RetroArch runtime. You do not manage packages. You do not edit systemd units unless you are showing off. The design goal is that a non-technical person can flash a card, plug in a controller, and be playing inside of a few minutes, while a technical person can still drop to a shell and micromanage every last shader. The homepage says "Get Batocera.linux 43.1" and means it literally: the product is a single image file.

The Wikipedia beetle problem

The naming collision is worth taking seriously for exactly one reason: it pollutes your search results. If you search the bare word "Batocera" you will land on the insect. If you search "batocera download" you will usually land in the right place, but the ad-riddled ROM-bundle resellers and mirror-of-a-mirror sites cluster around that query like flies. The rule for this entire exercise is simple and I will repeat it later: the canonical source is batocera.org and its own subdomains. Everything else is a convenience at best and a liability at worst.

Batocera versus the alternatives

Batocera is not the only retro-OS on the shelf, and pretending otherwise would be marketing. RetroPie is the venerable Raspberry-Pi-first option that you layer on top of Raspberry Pi OS. Lakka is the ultra-minimal official RetroArch distribution. EmuDeck is a script that configures emulators on top of SteamOS or Windows rather than replacing them. Batocera's distinguishing trait is breadth: one project builds images for x86_64 PCs, multiple Raspberry Pi generations, Odroid boards, and a long tail of Rockchip and Allwinner handhelds, all from a shared open codebase and a shared menu. If you want cycle-accuracy over convenience, that is a different conversation entirely, and it usually ends at an FPGA board like the ones the MiSTer community keeps pushing forward rather than at software emulation. Batocera is the convenience play, and it is a very good one.

Version 43.1: What You Are Downloading

Version numbers matter here because they determine which image you fetch, which bugs you inherit, and which mirrors are stale. The current stable line is 43.1, and understanding how it got that number saves you from grabbing something a year out of date.

The release timeline: 43 then 43.1

Batocera tracks its releases on a public timeline page that is candidly labeled "batocera 43 status (approximative dates)" and stretches across 2025 and 2026, which tells you the 43 cycle was a long one. The official changelog pins the point release you want, Batocera 43.1, to 30 May 2026. Version 43 proper landed a few weeks earlier in early May 2026; 43.1 was the bug-fix pass that followed. If you are downloading in the second half of 2026, 43.1 is the number you want, and the download page confirming it as recently as 26 August 2026 means you are not chasing a ghost.

The codename question, fact-checked

Here is where editorial discipline earns its keep. A popular third-party setup guide insists that 43.1 carries the codename "Glasswing." Batocera's own changelog does not. The 30 May 2026 date both sources cite is real and verifiable against the official changelog; the codename is not mentioned anywhere on batocera.org that I can locate. So treat "Glasswing" as community folklore rather than an official designation, and do not let a name you cannot verify send you to a download that is not the official one. The only string that matters when you fetch the image is the version: 43.1.

Why 43.1 and not the legacy 42 build

The official torrent index still lists the previous branch. You will see 2025-dated entries such as batocera-x86_64-42-20251006 and batocera-bcm2711-42-20251007 sitting right next to the 43.1 files. Those 42 images are not malware or a trap; they are simply the older stable line, kept around for hardware that regressed on the newer kernel or for people who need to reproduce a bug. Unless you have a specific reason, do not download the 42 image. It is a year behind, and the whole point of grabbing Batocera in 2026 is the 43 cycle's emulator and kernel updates. If your search engine or a lazy mirror surfaces a 42 link at the top, that is a signal the source is stale.

Prerequisites: Hardware and Software

You cannot flash what you cannot write to, and you cannot boot what your board cannot execute. This section is the boring, non-negotiable part. Read it before you download, because the answers here decide which file you download.

Hardware requirements by target

The requirements split cleanly by architecture. For a PC (x86_64): a 64-bit CPU from roughly the last decade, 4 GB of RAM as a comfortable floor (2 GB will boot but will sulk under heavier cores), and either a USB stick of 8 GB or larger to run live, or an internal SSD or HDD if you intend to install permanently. A GPU with working open drivers helps; integrated Intel graphics are fine for everything up to the demanding sixth-generation cores. For a Raspberry Pi 4 or Pi 400 (bcm2711): a microSD card of 16 GB or larger, ideally A1 or A2 rated for random I/O, a genuine 5V/3A USB-C power supply, and a heatsink or fan, because a naked Pi 4 under a busy PSX core will thermally throttle and you will blame the emulator. For the newer Raspberry Pi 5 and the growing roster of ARM handhelds, Batocera publishes separate images; the exact architecture token for those is listed on the download page next to each device, and you should read it off the page rather than guess.

The software you need on your desktop

To turn the downloaded image into a bootable card, you need exactly one writing tool. The safe default is balenaEtcher (the 2.x line is current; anything 1.19 or newer is fine), because it validates the write, refuses to target your system disk by default, and decompresses the .gz for you. If you are on a Raspberry Pi target, the Raspberry Pi Imager (1.8 or newer) is an equally good choice and can pick the SD device for you. Linux and macOS users comfortable at a terminal can skip both and use dd, which ships with the OS. You will also want a way to compute a checksum (sha256sum on Linux, shasum -a 256 on macOS, or certutil on Windows) so you can verify the download before you trust it.

Picking the right image before you click

Match the image to the board, full stop. An x86_64 image will not boot on a Raspberry Pi, and a bcm2711 image will not boot on your laptop, and in both cases the failure mode is an unhelpful black screen that sends beginners into a two-hour debugging spiral over what is fundamentally a filename mistake. Write down your target hardware now. If you are weighing whether to build a Batocera box at all versus buying a dedicated handheld with its own firmware, that is a legitimate fork in the road; a sub-hundred-dollar unit like the ones in our Miyoo Mini Plus breakdown ships ready to play but tops out around the PlayStation 1 ceiling, whereas a Batocera PC will chew through far heavier systems. Different tools, different budgets.

Which Image: Decoding the Filename

Batocera's filenames are not decoration. They encode everything you need to confirm you have the right build, and learning to read them is the single most useful skill in this guide.

The filename pattern, dissected

Every official image follows one pattern. Learn it once and you will never download the wrong file again.

batocera-[architecture]-[version]-[date].img.gz

# A real x86_64 example from the 43.1 line:
batocera-x86_64-43.1-20260529.img.gz

#  |         |        |     |
#  |         |        |     +-- build date (YYYYMMDD)
#  |         |        +-------- version (43.1)
#  |         +----------------- architecture (x86_64)
#  +--------------------------- project name (batocera)

The .img.gz suffix tells you it is a raw disk image compressed with gzip. Your writing tool will decompress it on the fly or you will decompress it manually; either way, the thing that lands on the card is the .img inside.

x86_64 versus bcm2711 versus the rest

The architecture token is the field that will bite you. Here is what the official torrent index actually lists for the current and previous branches, so you can see the pattern with real data rather than a hypothetical:

# Current stable (43.1), dated 2026-06-11 in the index:
batocera-x86_64-43.1-20260529.img.gz.torrent      # PCs, mini PCs, laptops
batocera-bcm2711-43.1-20260530.img.gz.torrent     # Raspberry Pi 4 / 400 / CM4

# Previous stable (42), still hosted for legacy hardware:
batocera-x86_64-42-20251006.img.gz.torrent
batocera-bcm2711-42-20251007.img.gz.torrent

Notice the detail that trips people up: within a single 43.1 release, the x86_64 build is stamped 20260529 and the Pi 4 build is stamped 20260530, one day apart. That date is the build date of that specific architecture, not the headline release date, and it differs per platform because each image is compiled on its own schedule. Do not panic if the dates on two images you downloaded do not match. As long as both say 43.1, they are the same release. This, incidentally, is why the third-party guide's tidy example of "batocera-x86_64-43.1-20260530" is slightly off from what the official index actually serves for x86_64; small discrepancies like that are exactly why you read the filename off the source of truth.

Torrent versus direct download

The download page offers both a direct HTTPS download and a torrent, and the dedicated torrents directory hosts the .torrent files for every architecture. Functionally the resulting .img.gz is byte-identical. The direct download is simplest and fine for a single fetch. The torrent is the courteous choice if the project's mirrors are under load, it resumes cleanly if your connection drops mid-download, and a good torrent client verifies each piece as it arrives, which is a form of integrity checking you get for free. Bandwidth-conscious readers, or anyone on a flaky connection, should prefer the torrent. Either way you are pulling from batocera.org's own infrastructure, which is the point.

Download and Install in 12 Steps

Here is the whole job, start to finish, with the reasoning for each step spelled out. Later sections drill into flashing, first boot, and games; this is the spine. Follow it in order and you will be in EmulationStation before your coffee is cold.

1. Confirm your target hardware. Write down whether you are flashing for a PC (x86_64) or a specific Raspberry Pi model (bcm2711 for the Pi 4). Rationale: this single fact selects your download and prevents the most common failure, the wrong-architecture black screen.
2. Go to the official download page. Open batocera.org/download and confirm it reads version 43.1. Rationale: the canonical source is the only source that is guaranteed current and unmodified; a stale mirror advertising version 42 is your cue to leave.
3. Select your architecture image. Pick the file whose architecture token matches step 1, for example batocera-x86_64-43.1 for a PC. Rationale: the filename is the contract; the token is the field that must match your board.
4. Choose direct or torrent. Click the direct download for a one-off, or grab the .torrent from the torrents index for resumable, self-verifying transfer. Rationale: both deliver the identical image; the torrent adds resilience and per-piece verification.
5. Note the published checksum. Record the SHA-256 (or MD5) shown next to the download. Rationale: you cannot verify integrity later without the reference value, and a corrupt image is a leading cause of boot failures.
6. Wait for the full download. Let the .img.gz finish completely; a partial file will flash without complaint and fail silently. Rationale: gzip images do not fail loudly when truncated, so a half-downloaded file looks fine until it does not boot.
7. Verify the checksum. Run sha256sum on the downloaded file and compare it to the value from step 5. Rationale: this is the ten-second insurance policy that separates a twenty-minute install from a ninety-minute one.
8. Insert your target card or drive. Put the microSD or USB stick into your desktop and note nothing else important is on it. Rationale: flashing is destructive; whatever is on this device is about to cease to exist.
9. Identify the device precisely. Use your OS disk tool or lsblk to note the exact device node or letter. Rationale: this is the step that, done wrong, overwrites your operating system instead of your SD card.
10. Flash the image. Point balenaEtcher, Raspberry Pi Imager, or dd at the image and the device, and write. Rationale: Etcher and Imager decompress the .gz and validate the write automatically; this is where the OS is physically written.
11. Move the card to the target and boot. Eject cleanly, transfer the card to your Pi or set your PC to boot from the USB stick, and power on. Rationale: a clean eject flushes buffers so the card is actually complete; the first boot is where Batocera takes over.
12. Let it expand, then connect and play. On first boot Batocera auto-expands its data partition, then drops you into EmulationStation; connect a controller and network, and add games. Rationale: the auto-expand claims the rest of the card for your userdata, and until it finishes you will not have room for a single ROM.

That is the download and install in twelve steps. The remaining sections are the detail behind steps 7 through 12, because those are the ones that actually go wrong. Everything from here is elaboration on where the twenty-minute path quietly turns into the ninety-minute one.

Flashing: Etcher, Imager, or dd

Flashing is writing the raw image to the block device sector by sector. There is no undo. This is the step where a beginner nukes their main drive and a veteran double-checks the device node one more time anyway. There are three good tools; pick by comfort level.

balenaEtcher, the safe default

If you have never done this, use balenaEtcher. It exists specifically to make this hard-to-reverse operation harder to get catastrophically wrong. Its workflow is three clicks: select the .img.gz (Etcher decompresses gzip natively, so you do not extract it first), select your target device (Etcher hides system drives by default and warns loudly if you override that), and click Flash. When it finishes it re-reads the card and validates every sector against the source, and it will tell you if the write did not take. That validation pass is why Etcher is slower than dd and why it is worth the wait: a card that fails validation here is a card that would have failed to boot later, and you have just found out in thirty seconds instead of thirty minutes.

Raspberry Pi Imager for Pi targets

On a Raspberry Pi target, the Raspberry Pi Imager is the equal of Etcher and arguably friendlier. Choose "Use custom" for the OS, point it at the Batocera .img.gz you downloaded, select your SD card, and write. It, too, decompresses and verifies. The one thing to ignore: Imager's advanced options for presetting Wi-Fi and SSH are tailored to Raspberry Pi OS and do not apply to Batocera, which manages those through its own config. Leave them alone and configure Batocera from its own menus after first boot.

dd for the command-line brave

If you live in a terminal, dd is direct and fast, and it will delete an entire disk without a flicker of hesitation if you fat-finger the target. The discipline that keeps you safe is to identify the device first and never assume. Expected output from the identification step looks like this:

$ lsblk
NAME        SIZE TYPE MOUNTPOINT
sda         931G disk
|-sda1      512M part /boot/efi
|-sda2      930G part /
sdb          29G disk               <-- this is the 32GB SD card
|-sdb1        4G part

# The SD card is /dev/sdb (the whole disk, NOT sdb1).

With the target confirmed as, say, /dev/sdb, decompress and write. You can do it in two steps or pipe it in one:

# Two-step: decompress, then write the raw image
$ gunzip batocera-x86_64-43.1-20260529.img.gz
$ sudo dd if=batocera-x86_64-43.1-20260529.img of=/dev/sdb bs=4M status=progress conv=fsync

# One-liner: decompress on the fly, never touching disk with the .img
$ zcat batocera-x86_64-43.1-20260529.img.gz | sudo dd of=/dev/sdb bs=4M status=progress

# When it finishes, flush and eject:
$ sync
$ sudo eject /dev/sdb

The status=progress flag gives you a live byte counter so you know it is working; conv=fsync forces the write to complete before dd returns so you are not fooled by a full buffer. And note the trap baked into the one-liner: unlike Etcher, dd does not decompress a .gz for you. Feed it the compressed file directly and you will write a gzip archive to the card, which boots into precisely nothing. Decompress first, or pipe through zcat.

First Boot: Expand, Connect, Pair

The card is written. Move it to the target device (or, on a PC, set the BIOS or UEFI to boot from the USB stick, disabling Secure Boot if the machine refuses) and power on. The first boot is different from every boot after it, and knowing what is supposed to happen keeps you from interrupting it.

The partition auto-expand

Freshly flashed, your card has a small system partition and a tiny userdata partition, because the image is sized to fit the smallest supported card. On the very first boot Batocera resizes that userdata partition to claim all remaining space, then reboots itself once. This is normal and expected. If you flashed a 256 GB card, this is the moment it becomes a 256 GB Batocera install rather than an 8 GB one. Do not yank the power during this pass. If you peeked at the card on your desktop right after flashing and it only showed a few gigabytes, that is why; the expansion has not run yet. Let it finish and you will land in EmulationStation with the full card available for games.

Connecting to the network

Ethernet needs no configuration; plug it in and Batocera has an address. For Wi-Fi, open the main menu (press START on the controller, or the keyboard) and go to Network Settings, enable Wi-Fi, select your SSID, and enter the key. Batocera stores this in its own config file, which we will look at in full later. A working network connection is not strictly required to play, but it is what makes the built-in updater, scraper (which fetches box art and metadata), and RetroAchievements work, so it is worth doing now. One caveat for Raspberry Pi users: some boards and some builds are fussy about 5 GHz networks; if your SSID does not appear, try the 2.4 GHz band.

Pairing controllers

A USB controller is plug-and-play; Batocera detects it and, on a new one, drops you straight into the button-mapping wizard. For Bluetooth, go to Controller Settings and Pair a Bluetooth Controller, put the pad into pairing mode, and select it from the list. The mapping wizard walks you through every button; take the ten seconds to do it properly, because a controller mapped wrong is the single most common reason a beginner thinks "the emulator is broken" when the emulator is fine and the A button is simply pointed at the wrong input. If you are outputting to a modern panel, this is also the moment you will appreciate a display that does the low-latency, high-contrast job well; our notes on the 2026 QD-OLED monitor pick apply just as much to a Batocera box as to a gaming PC.

Adding Games: ROMs and BIOS

Batocera ships with the machinery and none of the games, for reasons that are both legal and obvious. Getting content onto it is a matter of putting the right files in the right folders. This is also where the law and the lore intersect, so we will be precise.

Where Batocera looks for ROMs

Everything writable lives on the userdata partition, and it has a rigid, per-system folder layout. Over the network, Batocera exposes that partition as a share; on Windows you browse to the host in your file manager, on macOS or Linux you connect to the SMB share. The structure looks like this:

# The userdata layout Batocera expects (network share: smb://batocera/share):

/userdata/
|-- roms/
|   |-- snes/          <-- put Super Nintendo files here
|   |-- nes/
|   |-- n64/
|   |-- psx/           <-- PlayStation discs (.chd, .cue+.bin, .pbp)
|   |-- megadrive/     <-- Sega Genesis / Mega Drive
|   |-- gba/
|   |-- gb/
|   +-- ... (one folder per system, hundreds supported)
|-- bios/              <-- BIOS and firmware files go here
|-- saves/             <-- save files and save states
+-- system/            <-- batocera.conf and configuration lives here

Drop a file into the wrong system folder and it either will not appear or will launch under the wrong emulator. After copying games in, either reboot or, from the menu, update the gamelists so EmulationStation rescans. The folder name is the contract; get it right and the game shows up, get it wrong and you will swear the file is invisible.

The legal reality: dump your own

Here is the part the ROM-bundle resellers would prefer you skip. Distributing copyrighted ROMs is illegal in most jurisdictions, and downloading them is, at best, a legal grey area you are choosing to stand in. The clean path, the one nobody can send you a letter about, is to dump the cartridges and discs you already own. It is more work and it is the honest answer. We walked through exactly that for cartridge-based systems, start to finish, in our piece on dumping SNES carts in twelve steps, and the same principle covers your Genesis and Game Boy libraries. Batocera does not care where a legally-obtained file came from; it just wants it in the right folder. What you put there, and whether you own it, is on you.

BIOS files and where they go

Several systems, PlayStation and various others, will not run without their original BIOS or firmware, which Batocera cannot legally ship. These go in /userdata/bios/, and they must be the exact expected files, matched by checksum. Batocera has a built-in BIOS checker in its menu that lists every file each system wants, tells you which are present, and flags which are missing or the wrong hash. Use it. A "missing BIOS" error on a PlayStation game is not a bug in the emulator; it is a file you have not supplied yet, and the checker will name it precisely so you know what you are looking for.

Upgrading Without Reinstalling

Downloading Batocera once is the common case. Keeping it current without redoing the whole flash-and-configure dance is the part people miss, and it is genuinely painless because your userdata partition is deliberately separate from the system partition.

The built-in updater

The friendliest route never leaves the couch. Per Batocera's own documentation, from inside EmulationStation you press START and open Updates and Downloads, and the updater pulls the newest build on your current channel over the network. It replaces the system partition in place and leaves /userdata — your games, saves, and config — untouched. This is the recommended path for almost everyone, and it is why a network connection during first boot was worth setting up.

batocera-upgrade from the command line

If you prefer a shell, or you want to script it, Batocera exposes the same machinery as a command. SSH is available on the box (the default login is user root, password linux, which you should change immediately on any networked machine), and from there:

$ ssh root@batocera
root@BATOCERA's password:      # default is 'linux' -- change this

# Upgrade on the current stable channel:
[root@BATOCERA]# batocera-upgrade

# Or pin a specific build folder (per the official upgrade docs):
[root@BATOCERA]# batocera-upgrade [url of the build folder containing the version you want]

# Expected tail of a successful run:
Downloading ...  100%
Checking integrity ... OK
Installing to boot partition ... OK
Upgrade complete. Please reboot.

The bracketed URL form is the official syntax, and it is the escape hatch that matters: it lets you point the upgrader at the folder for an exact version rather than blindly tracking whatever the rolling channel serves. That is the difference between "update me" and "put me on precisely this build," and if you have ever been burned by an automatic update, you already know why the second one exists.

Pinning to a specific build

Some people, understandably, do not want the latest of everything the instant it drops. Maybe a specific emulator core regressed on your handheld, or maybe you just prefer to move deliberately. The URL-argument form of batocera-upgrade is how you stay on a known-good build: aim it at the build folder for the version you trust, and it fetches that one. This is the same philosophy behind keeping the legacy 42 images available — Batocera assumes some of its users have reasons to not be on the bleeding edge, and it does not fight them about it.

Common Pitfalls and Fixes

Most Batocera-download failures are not exotic. They are the same handful of mistakes, made in the same order, by people moving too fast. Here are the ones that account for the overwhelming majority of "it does not work" posts, and how to not be that post.

Download and image pitfalls

Pitfall 1 — Downloading the wrong architecture. The x86_64 image on a Pi, or a Pi image on a PC, boots to a black screen and nothing else. Fix: re-read the architecture token in the filename against your actual hardware and re-download the correct one. This is the number-one cause of first-boot failure and it is entirely preventable at the download page.

Pitfall 2 — Trusting a stale mirror or an unverified codename. Search results and resellers happily serve year-old version 42 links, and a plausible-sounding codename like "Glasswing" can lend a bad link false authority. Fix: download only from batocera.org and its torrents subdomain, and confirm the version reads 43.1. The name is not the version; the number is.

Pitfall 3 — Flashing a truncated or un-decompressed file. A partial .img.gz from a dropped connection, or feeding the raw .gz to dd without decompressing, both produce a card that will not boot. Fix: verify the SHA-256 after download (catches truncation), and use Etcher or Imager, which decompress for you, or pipe through zcat if you insist on dd.

Flashing and hardware pitfalls

Pitfall 4 — Flashing to the wrong disk. With dd especially, pointing of= at your system drive erases it, and there is no recovery short of a backup you hopefully have. Fix: run lsblk immediately before flashing, match the size to your SD card, and target the whole disk node, never a partition. When in doubt, use Etcher, which hides system drives on purpose.

Pitfall 5 — Cheap, fake, or worn-out cards. Counterfeit "256 GB" cards that are really 8 GB, or genuinely worn cards, fail Etcher's validation or corrupt userdata days later. Fix: buy A1/A2-rated cards from a reputable seller, and if validation fails, suspect the card and the reader before you suspect the image.

Pitfall 6 — Underpowered or dirty power on the Pi. A weak USB-C supply produces the undervoltage lightning-bolt icon, random freezes, and corrupted saves that look like software bugs. Fix: use a genuine 5V/3A supply for the Pi 4, add a heatsink, and stop diagnosing a power problem as an emulator problem. If cycle-accurate hardware is what you are actually chasing for a single system rather than a whole library, a dedicated FPGA console like the Analogue 3D for N64 sidesteps the emulation-tuning rabbit hole entirely, at the cost of doing exactly one thing.

Troubleshooting Table

When something has already gone wrong, work the table. It is ordered roughly by how often each problem shows up, and every fix is the first thing to try, not the only thing.

Reading the logs

When the table does not cover it, Batocera writes logs you can actually read. From the menu, the System Settings area exposes logging, and over SSH the EmulationStation and per-emulator logs live under the userdata tree. The single most useful habit is to launch the misbehaving game, let it fail, and then read the last twenty lines of the relevant log; nine times out of ten the failure names itself, whether it is a missing BIOS, an unsupported ROM format, or a core that crashed on load.

When to reflash instead of debug

There is a point of diminishing returns. If the card fails Etcher's validation, if the first boot never completes the partition expand across two attempts, or if the filesystem throws corruption errors, stop debugging the software and suspect the medium. Reflash to a different, known-good card. A surprising fraction of "Batocera is broken" cases are "this SD card is dying," and no amount of config editing fixes failing flash storage.

Advanced Tips and Full Config

Once you are booted and playing, the fun begins. Batocera is configured centrally through a single, human-readable file, and understanding it turns the OS from an appliance into something you can bend to your taste. We will end with a complete, working example you can adapt.

Overclocking, video, and integer scaling

Batocera exposes video mode, integer scaling, and shader configuration both through the menu and through config keys. Integer scaling (global.integerscale=1) keeps pixel-art crisp by scaling by whole numbers rather than smearing; it is the single setting most worth turning on for 2D systems. Rewind (global.rewind=1) buys you a few seconds of take-backs at a small performance cost, which is either a delight or a cheat depending on your temperament. On Raspberry Pi hardware, conservative overclocking can help the heaviest cores, but it is a power-and-heat trade, and it belongs to people who have already sorted their cooling — see pitfall 6.

Network shares and remote management

Batocera serves your userdata over SMB by default, which is how you copy games from your desktop without ever touching the card again. Enable or confirm it with system.samba.enabled=1, then browse to the host from your file manager and drop ROMs straight into the system folders over the wire. Combined with SSH for the command line, this means the Batocera box can go headless in a cupboard and you never physically touch it again. Change the default root password first, because a machine reachable at root/linux on your network is an open door.

The complete working configuration

Everything above lives in one file: /userdata/system/batocera.conf. You can edit it over SSH, over the SMB share, or through the menus (which write to it for you). Here is a complete, sane starting configuration with the keys that matter, annotated so you know what each one buys you:

## /userdata/system/batocera.conf
## A complete working starter config for Batocera 43.1

## --- Network ---
wifi.enabled=1
wifi.ssid=YourNetworkName
wifi.key=YourWifiPassword
system.hostname=BATOCERA

## --- Language and keyboard ---
system.language=en_US
system.kblayout=us

## --- Video and scaling ---
global.videomode=default
global.integerscale=1        ## crisp pixel-perfect 2D scaling
global.rewind=1              ## enable rewind (small perf cost)
global.bezel=default         ## decorative overlays for 4:3 systems

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

## --- RetroAchievements (off by default; fill in to enable) ---
global.retroachievements=0
global.retroachievements.username=
global.retroachievements.password=
global.retroachievements.hardcore=0

## --- Updates ---
updates.enabled=1
updates.type=stable          ## track the stable channel

## --- Network shares ---
system.samba.enabled=1       ## expose userdata over SMB for copying ROMs

Per-system overrides use a dotted prefix, so you can, for example, force a specific PlayStation core or a bespoke video mode for one system without touching the global defaults:

## Per-system overrides live in the same batocera.conf file.
## Prefix a key with the system name to scope it.

## Force the SwanStation core for PlayStation:
psx.core=swanstation

## Give N64 its own video mode without changing the global one:
n64.videomode=default

## Turn integer scaling off for one system you prefer stretched:
gba.integerscale=0

Edit, save, and reboot (or reload from the menu), and Batocera picks up the changes. The design principle throughout is that the menu and the file are two views of the same truth: anything you can click, you can also write here, and anything you write here shows up in the menu. That is the whole appeal of the thing — an appliance for people who want an appliance, and a Linux box for people who want a Linux box, from a single 43.1 image you downloaded in about twenty minutes.

For the canonical reference on any key or core mentioned here, the project maintains two sources worth bookmarking: the official Batocera wiki for OS-level configuration, and the libretro documentation for the individual emulator cores. When those two disagree with a random forum post, believe the wiki and the docs. And when a search engine tries to sell you a beetle, close the tab and go back to batocera.org/download. That is the whole game.