Batocera 43.1 Download: 12 Steps, 30 Min, 200+ Systems

What 'Glasswing' Actually Is

Batocera does not ask your permission. You write it to a USB stick, you tell the machine to boot from that stick, and for as long as the stick is plugged in your computer stops being a computer and becomes a games console. Nothing is written to your internal drive unless you deliberately go out of your way to install it there. That is the entire pitch, and it is a good one: a read-only Linux image that boots straight into EmulationStation with north of 200 emulator cores already wired up, configured, and waiting. No package manager, no dependency hell, no forum thread titled help RetroArch won't compile. You download an image, you flash it, you play. The friction that keeps most people off emulation on the desktop simply is not present here, and that is by design.

The current release is Batocera 43.1 'Glasswing', published on 30 May 2026. It is a point release — a bug-fix pass over Batocera 43 'Glasswing', which landed on 8 May 2026 and did the heavy lifting: new hardware targets, refreshed emulator cores, the usual round of fixes. Before that the line was Batocera 42 'Papilio', from 12 October 2025. If you are counting, that is three numbered releases inside roughly seven months, which tells you exactly what kind of cadence you are buying into. Batocera ships often, it ships numbered, and it does not sit on a stale image for two years the way some of its rivals do. If you want the short, no-commentary version of this walkthrough later, we keep a condensed 12-step quick-start alongside this one; this page is the version with the reasons attached.

The butterfly naming, and why it is not just whimsy

Batocera names its releases after butterflies — Papilio the swallowtail, Glasswing the transparent-winged one that looks like a pane of stained glass with legs — and this is not purely decorative. The project runs two update channels. Stable is what you are about to download: tested, boring in the good way, the branch you put on a box you actually want to use. Butterfly is the bleeding-edge branch, rebuilt constantly, where features land first and occasionally break in interesting ways. The pun is deliberate: the whole distribution is lepidoptera, and the beta channel is the butterfly that has not finished drying its wings. Keep the distinction in your head, because you will set it later in a config file, and picking the wrong one is the difference between a box that updates quietly in the background and a box that surprises you on a Tuesday with a broken PS2 core.

Free, open-source, and genuinely so

Batocera is free. Not freemium, not free-with-an-account, not free-until-the-Series-B. It is a community project funded by donations, with no advertising anywhere in the interface and no telemetry shaking you down for an email address. The source lives in the open on GitHub, and the image you pull from the download page is the same image everyone else pulls. This matters for a tutorial, because it means there is exactly one honest place to get the software — the official site and its mirrors — and a great many dishonest places that wrap the same free download in ad walls, redirect chains, or, worse, in a proprietary 'installer' that bundles junk. You do not need an installer. You need the image and a flashing tool, both of which cost nothing.

The widest hardware net in the hobby

The reason Batocera keeps coming up first in 2026 is reach. One project, one release, covers Raspberry Pi 2 through Pi 5 — yes, there is a proper official Pi 5 image, which is not a given elsewhere — x86_64 desktops and mini-PCs with genuine first-class support for the heavier systems, and more than twenty ARM handhelds. Version 43 alone added targets like the AYN Thor, the Odin 2 Mini, the Powkiddy X55, the Retroid Pocket 6, and the Radxa Dragon Q6A. If you own a retro handheld bought in the last two years, there is a real chance Glasswing already speaks its language out of the box. We put the Retroid Pocket 6 through its paces against the 5 if you are weighing that particular board; the point here is that Batocera's breadth is exactly why the download page opens by asking one question before anything else — which architecture are you on. Get that answer right and the rest of this is procedure.

Prerequisites & Requirements

Nothing here is exotic, but nearly every failure mode in the troubleshooting table further down traces back to skipping one line in this section. Read the whole thing before you plug anything in. The single most common way to ruin a Batocera install is to get the storage or the boot mode wrong, and both are decided before you write a single byte to anything.

Hardware, by architecture

What you need depends entirely on the target. Find your row, grab the matching image name, and ignore the rest — the images are not interchangeable, and the wrong one fails silently.

That last row is not a formality. Handhelds each get their own image because their screens, buttons, and system-on-chips differ, and a build for a neighbouring device will boot to a mangled display or not at all. If you are still shopping for the handheld itself, our rundown of the current Retroid Pocket lineup sorts out which board is worth the money before you commit to an image for it.

Storage: 16 GB is the floor, not the target

The absolute minimum is 16 GB. Batocera will boot and run from a 16 GB card. It will also, at that size, refuse to give the automatic updater enough headroom to stage a new build, which means you will be flashing every release by hand like it is 2015. The project's own recommendation, and mine, is 32 GB or larger. Thirty-two gigabytes buys room for the OS, the update mechanism, and a starter library in one card. If you are serious about disc-based systems, size for the ROMs and not the OS — a single PS2 or Wii collection will bury a 32 GB card without noticing, and you will want 256 GB or a USB SSD.

Buy a name you recognise. Counterfeit and end-of-life flash is the number-one cause of 'it flashed fine but won't boot,' and no tutorial step survives contact with a fake SanDisk pulled off a marketplace for the price of a coffee. An A2-rated microSD or a small USB SSD will both outrun and outlast the bargain-bin option, and the SSD in particular turns a Pi 5 or a mini-PC from 'tolerable' into 'genuinely snappy' when it is loading larger games.

Software on the flashing machine

You need exactly two things on the computer doing the flashing: the Batocera image, and a tool to write it. For the writer, any one of these current builds is fine:

• Raspberry Pi Imager (latest; the 1.9-series in mid-2026) — the friendliest option, and the one least likely to let you nuke your system disk by accident.
• balenaEtcher (latest 2.x) — cross-platform, and it verifies the write afterwards, which is worth the extra minute.
• USBImager (1.x) — tiny, fast, no telemetry, no ceremony; my pick once I already know which drive is which.

You do not need to decompress the download. Batocera ships as a .img.gz, and every tool above reads the gzip directly — unzipping it first just wastes disk. If your browser 'helpfully' unzipped it to a raw .img, that is still fine; if it unzipped it into something that is neither, your browser is the problem, and we deal with that in the pitfalls.

Choosing & Verifying the Image

Reading the download page

Everything starts at batocera.org/download. The page's first job is to make you choose an architecture, and it is worth slowing down here, because the name on the image must match the silicon in your target exactly. 'x86_64' is every ordinary 64-bit PC and mini-PC. 'rpi5' and 'rpi4' are what they say on the tin. Handhelds each have their own image, named for the device. Grabbing the x86_64 build for a Raspberry Pi is the single most common download mistake in the hobby, and it fails in a way that looks like a dead board rather than a wrong file — which is precisely why people waste an evening on it before checking the one thing that was wrong from the start.

The official installation guide on the Batocera wiki is the canonical reference for what each architecture expects, and if you are ever unsure which image maps to your board, that is the page to trust over any third-party 'setup guide,' most of which are SEO chum that copied the wiki and got a detail wrong on the way.

The direct mirror URLs

The download buttons resolve to mirrors, the primary being mirrors.o2switch.fr. If you would rather pull the image straight from a shell — scripting a build, or feeding a headless box — the stable x86_64 image lives at a predictable path. Grab it and confirm it is a whole file, not a truncated download or an HTML error page wearing a .gz extension:

# Pull the current stable x86_64 image straight from the mirror
wget https://mirrors.o2switch.fr/batocera/x86_64/stable/last -O batocera-x86_64-latest.img.gz

# Confirm it is a real gzip and not a half-downloaded error page
file batocera-x86_64-latest.img.gz
# -> batocera-x86_64-latest.img.gz: gzip compressed data, original size ...

# Sanity-check the size while you are at it (should be hundreds of MB, not KB)
ls -lh batocera-x86_64-latest.img.gz

Note the /batocera/ segment in that path. I am pointing at it deliberately, because a depressing number of copy-paste '2026 setup' tutorials drop it and print mirrors.o2switch.fr/x86_64/stable/last with no project name in the path. That URL 404s. The correct path, the one the official wiki uses, keeps /batocera/ in it. Remember this, because the exact same trap reappears when you run the upgrade command later, and the truncated version has fooled enough people to become its own troubleshooting row.

Verifying you got a whole file

You do not strictly need a cryptographic checksum to flash successfully — balenaEtcher and Raspberry Pi Imager both verify the write against what they read — but you do need to be sure the download completed. A partial .img.gz is the classic cause of a flash that reports success and then boots to a blinking cursor. The file command above is the cheap check: a truncated download is not valid gzip, and file will say so instead of reporting 'gzip compressed data.' If it does not identify as gzip, delete it and pull it again; do not flash it and hope. Cross-reference the build you pulled against the current and previous releases list if you want to be certain you are on 43.1 and not an older cached mirror copy.

The 12-Step Install: Flash to First Boot

How this is laid out

Twelve steps, from a blank drive to a playable menu, and on decent hardware with a fast card the whole thing is a thirty-minute job — most of which is the drive writing and the first-boot partition expansion, neither of which you should rush. Each step below carries both the action and the reason. Skip the reasons if you are in a hurry, but understand that the reasons are where the failures hide. A step done for the wrong reason tends to get undone at the worst moment.

The twelve steps

1. Download the image for your architecture. From the download page, pick x86_64, rpi5, rpi4, or your handheld's specific build. Why: the image is architecture-specific; the wrong one will not boot and gives you no useful error to work from, so getting this right first saves the most time.
2. Insert the target drive and identify it precisely. Note its size and, on Linux, its device node (/dev/sdb, /dev/mmcblk0, whatever it is). Why: flashing writes to the entire device and destroys everything already on it; misidentifying the disk is how people erase the photos they meant to back up.
3. Open your flashing tool and choose 'Use custom.' In Raspberry Pi Imager: CHOOSE OS, scroll to the bottom, select 'Use custom,' then point it at the .img.gz. Why: Batocera is not in the built-in OS list, and 'Use custom' is the sanctioned path; the tool reads the gzip without you decompressing anything.
4. Select the storage device — and triple-check it. Confirm the size and label match the drive you intend to sacrifice. Why: this is the irreversible step. The tool has no idea which drive holds your life's work and which one is the empty stick; that judgement is entirely yours.
5. Write, and then wait. Start the flash and leave it alone until it reports done, including any verification pass. Why: interrupting a write leaves a half-image that boots to nothing and looks, unhelpfully, like dead hardware.
6. When Windows offers to format the new drive, cancel. After writing, Windows sees Batocera's Linux partitions as 'unformatted' and pops up an offer to fix them. Why: accepting that offer wipes the image you just spent five minutes writing. Click Cancel. Every single time. This one prompt has eaten more first installs than any other.
7. Move the drive to the target machine and set it to boot from USB/SD. On a PC that means the one-time boot menu or the BIOS/UEFI boot order, and you may also need to disable Secure Boot. Why: the machine will cheerfully ignore your Batocera stick and boot its internal OS unless told otherwise, and Secure Boot blocks Batocera's loader on some boards outright.
8. Boot Batocera and let the partition expand. On the very first boot it grows the userdata partition to fill the whole drive, then reboots itself once. Why: this is what turns a small image on a 128 GB card into 120-plus GB of usable space; power off in the middle and you corrupt the card and start over.
9. Land on EmulationStation and pair a controller. Hold a button on your gamepad to begin pairing, or plug one in over USB. Why: the entire interface is gamepad-first, and pairing now spares you fighting the menus with a keyboard for the next half hour.
10. Set language, timezone, and video output. Press START, open SYSTEM SETTINGS, and set them. Why: this gets clocks, save-file timestamps, and screen resolution correct before you pour hours of ROMs and metadata in on top of the wrong defaults.
11. Connect to the network. Ethernet just works; for Wi-Fi go to MAIN MENU, then NETWORK SETTINGS, and join your network. Why: you need the network for updates, for scraping box art and metadata, and for the file share you are about to use to load games.
12. Note the IP address and confirm the share is live. NETWORK SETTINGS shows the IP; the box now advertises itself as BATOCERA on the LAN. Why: confirming the machine is reachable before you try to copy gigabytes of ROMs onto it saves an entire support thread's worth of blind guessing.

Expected output along the way

Two checkpoints are worth actually looking at rather than assuming. After the write in step 5, on a Linux flashing box, lsblk should show Batocera's two partitions — a small read-only boot partition and the large userdata one:

$ lsblk /dev/sdb
NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
sdb      8:16   1  28.9G  0 disk
├─sdb1   8:17   1     2G  0 part   # BATOCERA boot (read-only)
└─sdb2   8:18   1  26.9G  0 part   # SHARE / userdata (grows on first boot)

And once you are on the network and into an SSH session (covered just below), batocera-info confirms the build number and the hardware it believes it is running on. Treat the exact fields as illustrative — they vary by machine — but the version line at the top is the thing to verify:

$ batocera-info
Batocera 43.1 (Glasswing)
Arch:   x86_64
Board:  generic-x86_64
Memory: 15.5 GiB total
Storage: userdata 118 GiB (expanded)

If batocera-info reports a different version than you meant to install, you flashed an old cached image — go back to the download page and pull it again. If the storage line still shows the tiny pre-expansion size, first boot did not finish its partition grow; re-flash and let step 8 complete.

Adding ROMs & BIOS Over the Network

The BATOCERA share

Batocera exposes its userdata over SMB, so the sane way to load games is across the network rather than by yanking the card in and out. On the LAN the box announces itself as BATOCERA, and the writable tree hangs off a share called share. From Windows or macOS you reach it by typing a network path into the file manager; from Linux you point your file manager at the same address. If the hostname will not resolve on your network — some routers are bad at this — substitute the IP you noted in step 12.

Windows Explorer:    \\BATOCERA\share
macOS Finder:        smb://BATOCERA.local/share
Linux file manager:  smb://BATOCERA.local/share

# If the name will not resolve, use the IP instead:
Windows:  \\192.168.1.42\share
mac/Lin:  smb://192.168.1.42/share

Where the files go

Inside the share the layout is exactly what you would hope for. Games live under roms/, in one subfolder per system — roms/snes, roms/genesis, roms/psx, roms/n64, and so on down the list. BIOS files, for the systems that require one you legally own, go under bios/. Each system folder carries an _info.txt, and the wiki's per-system pages spell out which file extensions that emulator accepts and which BIOS revisions (by hash) it expects. Respect those specifics: the second-most-common 'why won't this game load' after a bad ROM is a BIOS in the wrong folder or the wrong revision entirely. The whole tree you see over the share is the /userdata partition on the device, which is the same partition that survives every update — so anything you put here is safe across upgrades.

Refreshing the games list

Batocera does not watch those folders live, which trips up almost everyone once. After you drop files in over the share, you have to tell EmulationStation to rescan. From the interface, press [START], open GAME SETTINGS, and choose UPDATE GAMELISTS. The newly added systems and titles appear once it finishes. If a whole system is missing rather than a single game, you almost certainly put the ROMs in a folder name Batocera does not recognise — check the exact system folder names against the wiki rather than guessing. This is also the moment to run the scraper if you want box art and metadata; it pulls cleanly now that the network is up.

Updating & Downgrading with batocera-upgrade

The easy path: the built-in updater

Most people never need a shell for this. MAIN MENU, then UPDATES & DOWNLOADS, runs the update for you with a progress bar, and the same menu is where you choose your branch: UPDATE TYPE toggles between stable and butterfly. Whatever route you take, one promise holds across every method Batocera offers: your userdata is never touched. ROMs, saves, scraped metadata, per-game configs — all of it lives on the userdata partition, and both upgrades and downgrades leave that partition completely alone. This is the single best reason to stop hoarding old images 'just in case': the update mechanism is genuinely non-destructive.

The SSH path: batocera-upgrade

Since Batocera 5.23 the sanctioned way to move between versions from a shell is the batocera-upgrade command, documented on the wiki's manual upgrades and downgrades page. Run bare, it updates to the latest of whatever branch you are on. Handed a URL, it goes exactly where you point it — which is how you downgrade to a specific build, or move deliberately between architectures. Get in over SSH first (default user root, default password linux, per the wiki's SSH access guide):

# Connect over SSH (default user root, default password linux)
ssh root@batocera.local

# Update to the latest STABLE build for x86_64, then reboot
batocera-upgrade https://mirrors.o2switch.fr/batocera/x86_64/stable/last
reboot

Two warnings the official wiki puts in bold, and so will I. First, that URL is architecture-specific: do not paste the x86_64 path onto a Raspberry Pi and expect anything but grief — swap in the Pi's own path. Second, mind the /batocera/ segment one more time. The truncated URL that circulates on copycat 'setup' sites — the one missing the project name — is simply wrong, and it produces a 404 that people misread as a broken mirror. It is not the mirror; it is the URL.

The manual path: boot.tar.xz

On Batocera 39 and newer you can stage an upgrade entirely by hand, which is the move when the box has no internet, when you are pinning one exact build across several machines, or when you simply do not trust an over-the-air update on install night. Download the matching boot.tar.xz for your architecture, drop it into /userdata/system/upgrade, and let Batocera consume it. Because that folder lives under the share, you can place the file from another machine entirely:

# From another computer, copy the file onto the share:
#   \\BATOCERA\share  ->  system/upgrade/boot.tar.xz

# Then, over SSH, confirm it is staged and trigger the upgrade:
ls -la /userdata/system/upgrade/
# -rw-r--r-- 1 root root  ...  boot.tar.xz

batocera-upgrade
reboot

The exact trigger for a staged file is documented on that same wiki upgrade page — follow it rather than a forum comment, because the manual-upgrade flow is the one third parties most often garble. Everything under /userdata is preserved through this, same as the automatic path.

Five Pitfalls That Wreck a Fresh Install

Before the write

Pitfall 1 — the wrong architecture image. The x86_64 build on a Pi, or a neighbouring handheld's build on your handheld, will not boot, and it fails looking like dead hardware. Fix: match the image name to your target exactly, using the download page and the wiki's install guide as the authority, not a YouTube title.

Pitfall 2 — the browser mangled the download. Chrome and Safari sometimes auto-decompress or re-package a .img.gz, leaving you with a file your flasher cannot read, or a truncated one that flashes to a dead card. Fix: keep the .gz as delivered, and run file on it before flashing; if it does not report 'gzip compressed data,' re-download it.

During and just after the write

Pitfall 3 — accepting Windows' 'format this drive' prompt. After a successful flash, Windows sees the Linux partitions as unformatted and offers to help. Helping wipes Batocera. Fix: click Cancel, and if you clicked the wrong thing, re-flash — there is no undo.

Pitfall 4 — cheap or fake flash media. Counterfeit cards report a size they do not have and corrupt on the first-boot partition grow, or simply refuse to boot after a clean flash. Fix: use a reputable A2 microSD or a small USB SSD from a seller you trust; this is not where you save four dollars.

At first boot and beyond

Pitfall 5 — Secure Boot or the wrong boot order. The machine ignores your stick and boots its internal OS, or Secure Boot blocks Batocera's loader outright. Fix: use the one-time boot menu, set USB/SD ahead of the internal disk, and disable Secure Boot on x86_64 boards that refuse otherwise.

Pitfall 6 — powering off during partition expansion. Kill the power while first boot is growing userdata and you corrupt the card mid-resize. Fix: leave it alone until it reboots itself; if you interrupted it, re-flash and let step 8 finish this time.

Pitfall 7 — the truncated upgrade URL. The copy-paste mirror path missing /batocera/ 404s and gets blamed on the server. Fix: always use the full mirrors.o2switch.fr/batocera/<arch>/stable/last form, matched to your architecture.

Troubleshooting: Symptoms, Causes, Fixes

Boot and display problems

Roughly nine out of ten 'it won't start' reports are one of three things: the wrong image, an under-powered supply, or bad media. Work through those before you suspect the software, because the software is the same read-only image that boots fine for a few hundred thousand other people.

Network, update, and game problems

The second cluster is everything downstream of a working boot — the share not showing up, games not appearing, an upgrade that seems to do nothing. These are almost always a refresh you did not run or a branch you did not set, not a bug. The table sorts the common ones by symptom.

The reference table

Advanced Tips

Make system changes stick: batocera-save-overlay

The system partition is read-only by design — that is the whole reason Batocera is so hard to break, and why a bad session is cured by a reboot rather than a reinstall. The trade-off is that edits to system files outside userdata do not persist across reboots unless you commit them to the overlay. After you have hand-edited something that lives on the read-only tree, save it:

batocera-save-overlay

To be clear about scope: batocera.conf itself lives under /userdata and needs none of this — it persists automatically. The overlay is only for the deeper system files you have no business touching unless you know exactly why, which is most of the point.

Living on the butterfly branch

If you want features the moment they land — a new core, a fresh handheld target, a fix that has not reached stable — switch to butterfly, either through MAIN MENU → UPDATES & DOWNLOADS → UPDATE TYPE, or by setting updates.type=butterfly in the config. Do it on a box you can afford to have misbehave, and never the night before you need the thing to work. Butterfly is where bugs are found, which is a polite way of saying it is where bugs live. For a box you actually rely on, stay stable and let other people test the wings.

SSH hygiene and useful commands

The default credentials are root / linux, which is fine on a trusted home LAN and reckless anywhere a stranger can reach the machine. Turn on Enforce Security (SYSTEM SETTINGS → SECURITY) to set your own password and require authentication on the network shares. A handful of commands are worth committing to memory, all documented on the wiki's SSH page:

batocera-info                      # hardware + build summary
batocera-es-swissknife --restart   # bounce EmulationStation without a full reboot
batocera-store list                # browse installable content packs
batocera-support                   # bundle logs for a bug report
batocera-save-overlay              # persist system-partition edits

If your ambitions run past software emulation toward cycle-accurate FPGA hardware, that is a different rabbit hole entirely — we walked through the MiSTer Multisystem 2 for exactly that itch. But for one drive that plays everything from the Atari era to the sixth generation, Batocera on a decent mini-PC is very hard to argue with, and it is free.

A Complete Working batocera.conf

The annotated file

Everything the OS remembers about your preferences lives in one flat file: /userdata/system/batocera.conf. It is plain key=value, it survives every update, and it is the fastest way to bring a fresh box up to a known state or to clone a setup across machines. Below is a complete, sane starting config — SSH on, Samba on, stable branch, sensible emulator defaults. The keys reflect Batocera's documented schema; treat this as a template and cross-check the wiki for anything you change, because defaults do drift from release to release and a key that was optional in 42 may behave differently in 43.1.

# /userdata/system/batocera.conf  --  annotated starter (Batocera 43.1 Glasswing)
# Plain key=value. A leading # disables a line.

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

## --- Remote access ---
system.ssh.enabled=1        # SSH server on (root / linux until you change it)
system.samba.enabled=1      # \\BATOCERA\share for ROM and BIOS transfer
system.security.enabled=0   # set 1 (Enforce Security) to require a password

## --- Updates ---
updates.enabled=1
updates.type=stable         # 'butterfly' = bleeding-edge beta branch

## --- Network (Wi-Fi; leave disabled for Ethernet) ---
wifi.enabled=0
# wifi.ssid=YourNetwork
# wifi.key=YourPassword

## --- Audio ---
audio.volume=90
# audio.device=             # set only if HDMI/analog picks the wrong output

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

## --- Global emulator defaults (override per-system in the UI) ---
global.smooth=1             # bilinear smoothing
global.rewind=0
global.autosave=0
global.netplay=0
global.retroachievements=0
# global.retroachievements.username=
# global.retroachievements.password=
global.shaderset=none

Applying it without a reboot dance

Edit the file over SSH with your editor of choice, or simply drop a prepared copy onto the share at system/batocera.conf from another machine. A single reboot applies everything cleanly. The network and update-branch keys in particular want that reboot to take effect, so do not judge a change by whether it appears instantly. Because the file lives on userdata, it rides through every future upgrade untouched — which is exactly why keeping a known-good copy of it somewhere off the device is the closest thing Batocera has to a backup worth making.

What not to touch

Leave the read-only system partition alone. Do not chase a few frames by editing files outside /userdata unless you are genuinely prepared to batocera-save-overlay and own whatever breaks. The whole value proposition here is a box that you cannot easily wreck and that comes back clean from any reboot; every edit you make on the read-only side chips away at that guarantee. Batocera's own configuration surface — this file, the in-menu settings, and the per-system overrides — is deep enough to do almost anything you actually want, and it does it without putting your install one bad save away from a re-flash. If you want to go deeper on how the underlying cores are chosen and tuned, our walkthrough of RetroArch cores in 2026 covers the libretro layer Batocera is built on, and the upstream Batocera source on GitHub is where the definitive answer to any 'what does this key really do' question ultimately lives.