Batocera Download 2026: v43.1 in 12 Steps, 30 Min

There is a particular flavor of disappointment reserved for the person who buys a mini PC "for emulation," installs Windows, then a frontend, then forty-one emulators, then spends three weekends fighting controller mappings and DLL hell. Batocera exists to end that person's suffering. It is a self-contained Linux distribution that boots straight into a game menu, ships with the emulators already wired up, and asks nothing of you except a USB stick and the willingness to read a BIOS screen.

This is a download-and-flash tutorial, not a philosophy lecture, so here is the short version of what you are about to do: grab a compressed disk image from the official site, verify it, write it byte-for-byte to a USB drive or SD card, disable one BIOS setting that Microsoft would prefer you leave on, and boot. Twelve steps, roughly thirty minutes if your USB drive is not from a cereal box, and you will have Batocera 43.1 — the current stable release — running on hardware that a week ago was pushing spreadsheets.

We will use the real version numbers, the real filenames, and the real download URLs, because it is 2026 and there is enough fabricated tutorial content on the internet already. Batocera 43.1 shipped on May 20, 2026. The feature release it patches, 43 "Glasswing," shipped on May 8, 2026. Everything here traces back to the project's own changelog and wiki. Let's get into it.

What Batocera Actually Is

Before you flash anything, understand what you are flashing, because roughly half of all "Batocera problems" posted online are actually "the user assumed it was Windows" problems.

A read-only Linux appliance, not a desktop

Batocera is a purpose-built Linux distribution — an appliance. The operating system itself lives on a compressed, effectively read-only system partition. Your saves, ROMs, scraped artwork, BIOS files, and configuration all live on a separate writable partition called userdata. This split is deliberate and it is the single most important architectural fact about the distro: you can wipe and reinstall the OS without touching your library, and "editing system files" the way you would on Ubuntu is mostly not a thing you do. You change behavior through one configuration file and a menu, not by apt-installing packages. The frontend you see on boot is EmulationStation; the emulators behind it are a mix of libretro cores running under RetroArch and standalone emulators like Dolphin, PCSX2, and Azahar. If you have ever assembled a RetroArch setup by hand — and if you want to appreciate what Batocera is doing for you, our walkthrough of installing 200+ RetroArch cores in 12 steps is the long way round — you will recognize the machinery immediately. Batocera just did the assembly for you.

Free as in freedom, and free as in beer

Batocera.linux is 100% open source. The entire build system, every recipe, every default config, is published in the official repository at github.com/batocera-linux/batocera.linux. It costs nothing to download and nothing to use; there are no licensing fees, no "pro" tier, no account. The project's own work is licensed CC-BY-NC-SA — Creative Commons Attribution-NonCommercial-ShareAlike — which is the part the resellers on marketplace sites conveniently forget. If someone is selling you an SD card "pre-loaded with Batocera," the distro on it is free, the NonCommercial clause puts them on shaky legal ground for selling it, and the games on it are a separate legal problem entirely. Which brings us to the next point.

It ships zero games — that part is on you

Batocera contains emulators. It contains no games, no ROMs, and none of the system BIOS files that certain platforms legally require. This is not an oversight; it is the only way a project like this can exist in the open. What you do with your own cartridge dumps is between you, your conscience, and the jurisdiction you live in. The Machine is a tutorial, not your lawyer, but the lore is simple: emulators are legal, distributing copyrighted ROMs is not, and dumping games you personally own occupies a grey zone whose exact shade depends on where you are standing. Batocera hands you a fully-built arcade and leaves the coin-op economics to you.

Version 43.1 and Glasswing

Version numbers matter here because the wrong image will cost you an evening. As of this writing the stable line is 43.1, and understanding what separates it from plain 43 tells you which download to trust.

Glasswing: what 43 actually changed

Batocera 43, codenamed "Glasswing," was released on May 8, 2026. Its headline feature is first-class support for x86_64 handhelds — the AMD- and Intel-powered pocket PCs that have flooded the market — delivered through the preferred x86_64-v3 image. That "-v3" suffix is not decoration; it names a specific CPU microarchitecture feature level (AVX2 and friends) that every reasonably modern x86 chip supports and that lets the build target faster code paths. Under the hood, Glasswing also moved the desktop stack onto Wayland with the LabWC compositor, but for a gaming appliance that is plumbing you will never see. The point of Glasswing is the acknowledgment that x86 handhelds are now a category worth a dedicated image, not an afterthought bolted onto the desktop build.

43.1: the stability patch that matters

Batocera 43.1 landed on May 20, 2026, and it is exactly what a point release should be: no new features, just the bug list from the first two weeks of real-world use. The fixes that will matter to you on day one:

• Microsoft controllers that version 43 misidentified as keyboards — a genuinely maddening bug where your Xbox pad types instead of plays — are correctly detected again.
• LR-MAME lightgun support, broken in 43, works. If you own a Sinden or a GunCon rig, this is the difference between a light-gun cabinet and an expensive paperweight.
• LR-Dolphin options — the per-game core settings for GameCube and Wii — are functional again after regressing in 43.
• The TheXTech asset problem is resolved; the engine now correctly requires a minimum of version 1.3.7 assets to run. (TheXTech is the open-source reimplementation of Super Mario Bros. X, in case a lesser tutorial told you otherwise.)

The practical takeaway: there is no reason to install 43 today. Install 43.1. If you already flashed 43, you do not need to reflash — you update in place, which we cover in the advanced section.

The regressions: DraStic, Azahar, Apple II GS

A good tutorial tells you what got worse, too, and version 43 was not shy about dropping things. The closed-source Nintendo DS emulator DraStic was removed entirely, so DS emulation moves to open cores like melonDS — and old DraStic save states do not carry over. The 3DS situation shifted twice: the fork Azahar Plus was replaced by the upstream source project Azahar, and 3DS ROMs must now be decrypted — encrypted CIA/CCI dumps will no longer load. More conspicuously, Apple II GS support via MAME was dropped, temporarily, pending the next MAME upgrade that will restore it. If your retro tastes run to 1986 Apple hardware you are in a very small club and will want to keep an older install around; for everyone else it is a non-event. All of it is the kind of detail that separates the changelog from the marketing, and the full list lives on the project's own changelog page.

Prerequisites and Requirements

Everything in this section is the boring part that determines whether the exciting part works. Skip it at your own risk.

Hardware: the floor and the sane middle

The hardware floor is genuinely low. Batocera asks for a minimum of 1 GB of RAM (2 GB recommended) and a minimum of 16 GB of storage, with 32 GB recommended — and note that a 16 GB install sits below the threshold for automatic updates, so if you cheap out on the card you forfeit in-place upgrades. Above that floor, "will it run" depends entirely on what you want to emulate:

• 8-bit and 16-bit systems (NES, SNES, Genesis, Game Boy, arcade up to CPS-2): almost anything, including a Raspberry Pi 4 or a decade-old thin client.
• PS1, N64, Dreamcast, PSP: a modern quad-core x86 chip or a Pi 5 handles these comfortably.
• GameCube, Wii, PS2, 3DS: you want a real x86-64 CPU from the last several years and, ideally, a discrete or modern integrated GPU.
• Switch, PS3, Wii U: a genuinely fast desktop or a current x86 handheld SoC — and even then, patience.

For a clean, no-drama build the community consensus lands on a small x86 mini PC — the Beelink Mini S12 is a frequently-cited example — and the Framework 13 laptop is the other machine the official install notes call out by name. Both boot the same x86_64 image; the only real difference is the keyboard shortcut to reach the boot menu.

Software: what you need on the host machine

To create the installation media you need exactly three things, and none of them cost money:

1. The Batocera .img.gz image from the official download page.
2. A flashing tool. The official wiki recommends a GUI imager — Balena Etcher, Raspberry Pi Imager, or USBImager — for everyone, and explicitly does not recommend raw dd for beginners. On Linux or macOS the dd command remains the transparent, scriptable option for people who know precisely what they are doing. On Windows, Rufus also works.
3. Optionally, a checksum tool — sha256sum on Linux, shasum -a 256 on macOS, CertUtil on Windows — to verify the download before you trust it.

That is the entire software bill of materials. You do not need a license, a Batocera account, or even an internet connection on the target machine during install — though you will want one afterward for scraping artwork and pulling updates.

The USB/SD card reality check

This is where most first attempts die. Batocera can either run from the USB stick as a live system or be installed to an internal disk. Either way, the flashing target must be:

• At least 16 GB to meet the floor, and realistically 32 GB or more if you plan to run Batocera live off the stick and store games on it.
• A real, name-brand drive. Counterfeit-capacity USB sticks and no-name SD cards are the single most common cause of "it flashed fine but won't boot." A SanDisk, Samsung, or Kingston card from a reputable seller will save you hours.
• Expendable. Flashing erases the entire device. Everything on it is gone. There is no "are you sure" that will rescue your vacation photos.

For a permanent build, flash to a USB stick, boot it, then install to the machine's internal SSD or NVMe. For a try-before-you-commit run, boot live off the stick and touch nothing internal. Both paths start with the same download.

Choosing the Right Image

The download page presents a menu of images, and picking wrong is the most common pre-flight mistake. Here is how to read it.

x86_64 vs x86_64-v3: the CPU generation question

For any PC, laptop, mini PC, or x86 handheld, the two candidates are the plain x86_64 image and the newer x86_64-v3 image introduced as the preferred build in Glasswing. The distinction is CPU feature level:

• x86_64-v3 assumes AVX2, BMI, FMA, and related instructions — present on Intel Haswell (2013) and AMD Excavator/Zen (2015) and everything since. If your machine is from roughly 2015 onward, this is your image, and it is the one the project now prefers.
• Plain x86_64 is the compatibility fallback for older or unusual chips that lack the v3 feature set. If a v3 image refuses to boot on ancient hardware, this is the retreat.

When in doubt on a modern machine, take x86_64-v3. The download filename encodes the choice: the 43 build shipped as batocera-x86_64-x86_64-43-20260508.img.gz, and the 43.1 PC image follows the same pattern as batocera-x86_64-x86_64-43.1.img.gz. The doubled x86_64-x86_64 is not a typo — the first token is the architecture family, the second the specific target.

Single-board computers and the Pi family

If your target is a Raspberry Pi, an Odroid, or one of the many ARM single-board computers, you do not download the x86 image. The download portal lists device-specific SBC images because ARM boards need bootloaders and kernels tailored to their exact silicon — a Pi 5 image will not boot a Pi 4, and neither will boot an Odroid. Pick the exact board. This is the number-one SBC mistake: grabbing "the Batocera image" generically and then wondering why the board flashes a rainbow screen and dies. Unlike RetroPie, which still has no official Pi 5 image, Batocera ships one — another reason the SBC crowd keeps migrating over.

Steam Deck and x86 handhelds

The Steam Deck is, under the hood, an x86-64 machine, and Batocera treats it as one — the download page calls it out specifically. Glasswing's entire reason for the x86_64-v3 push was this class of device: Deck, ROG Ally, and the growing field of pocket x86 PCs. If you are weighing a dedicated retro handheld against a Deck for this exact purpose, the trade-offs we lay out in the Retroid Pocket generational comparison apply directly — but for any x86 handheld, the image you want is x86_64-v3, flashed to a fast microSD or an external SSD so you are not overwriting SteamOS unless that is genuinely your intent.

Download and Verify

Now the actual downloading. This section is short because the project has made it hard to get wrong — provided you use the real source.

Where the real download lives

There is exactly one official download portal: batocera.org/download. It lists device-specific images for PC, Steam Deck, and single-board computers, and it is the only source The Machine will vouch for. The project has been maintained by the Batocera.linux team since 2016, with copyright spanning 2016–2026, and its download infrastructure and mirrors are part of that lineage. Do not download Batocera from a random file locker, a YouTube description's shortened link, or a marketplace listing. The distro is free; there is no reason to source it from anywhere but the origin, and every reason not to.

Select your device on the portal, choose the x86_64-v3 image for a modern PC or handheld, and start the download. You will receive a single compressed file with a .img.gz extension, on the order of a couple of gigabytes.

Verifying you got the whole file

A truncated or corrupted download is the invisible cause of a huge share of failed flashes: the image looks fine, the flasher writes it, and the machine won't boot because the last few percent of the file never arrived. Verify before you flash. The download page publishes checksums; compare them.

# Linux
sha256sum batocera-x86_64-x86_64-43.1.img.gz

# macOS
shasum -a 256 batocera-x86_64-x86_64-43.1.img.gz

# Windows (PowerShell)
CertUtil -hashfile batocera-x86_64-x86_64-43.1.img.gz SHA256

Expected output is a single 64-character hexadecimal string. It must match the checksum published next to the image on the download page, character for character:

$ sha256sum batocera-x86_64-x86_64-43.1.img.gz
7b1e9c0f4a2d8e6b5c3a1f0d9e8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c  batocera-x86_64-x86_64-43.1.img.gz

If it does not match, delete the file and download again. Do not proceed. A mismatched hash flashed to a stick is thirty minutes you will never get back. (The hash above is illustrative — use the live value from the download page, which changes with every build.)

Extracting the .img.gz

Modern flashing tools — Etcher, Raspberry Pi Imager, USBImager — will happily read the compressed .img.gz directly and decompress on the fly, so you often do not need to extract manually. If you are using dd, or a tool that insists on a raw .img, decompress first:

# Linux / macOS — keep the original .gz with -k
gunzip -k batocera-x86_64-x86_64-43.1.img.gz
# result: batocera-x86_64-x86_64-43.1.img

On Windows, 7-Zip opens .gz archives directly. Whichever route you take, you now have — or your tool can see — a raw disk image ready to write.

Flashing in 12 Steps

Here is the whole procedure, start to finish, with the reasoning behind every step — because a step you understand is a step you can recover from when it goes sideways. Total time: about thirty minutes, most of it the write itself.

Steps 1 to 5: prepare and verify

1. Download the correct image from batocera.org/download — x86_64-v3 for a modern PC or handheld, or the exact SBC image for your board.
   Why: the architecture must match the silicon. An x86 image will not boot an ARM Pi, and a v3 image will not boot a pre-2015 chip.
2. Verify the SHA256 checksum against the value on the download page.
   Why: a corrupted download is indistinguishable from a good one until it fails to boot. Sixty seconds of hashing saves an hour of confusion.
3. Extract the image if your flasher needs a raw .img, or leave it compressed for Etcher and Pi Imager.
   Why: some tools read .img.gz natively; dd does not. Knowing which you are using prevents a "why is this file not a disk image" dead end.
4. Insert your USB stick or SD card and identify it precisely. On Linux run lsblk; on Windows note the drive number in Disk Management; on macOS use diskutil list.
   Why: the next step erases whatever device you name. Naming the wrong one erases your system disk. This is the step people skip and regret.
5. Close every file-browser window pointing at the card and unmount it.
   Why: a mounted partition can cause a partial or failed write, and some systems will "helpfully" rewrite the partition table mid-flash.

Expected output from step 4 on Linux, with a 32 GB stick showing up as sdb:

$ lsblk
NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
sda      8:0    0 931.5G  0 disk
├─sda1   8:1    0   512M  0 part /boot/efi
└─sda2   8:2    0   931G  0 part /
sdb      8:16   1  28.9G  0 disk
└─sdb1   8:17   1  28.9G  0 part /media/usb

Here sdb is the target. sda is the internal disk — do not touch it. The RM column reading 1 (removable) is your confirmation you have the right device.

Steps 6 to 9: write the image

6. Open your flashing tool and select the Batocera image. In Balena Etcher, "Flash from file" and choose the .img.gz or .img.
   Why: selecting the image before the target is Etcher's guided order and reduces the odds of a wrong-device mistake.
7. Select the USB/SD device you identified in step 4 — by size and label, not by guessing.
   Why: Etcher hides system drives by default, but external USB-to-SATA enclosures can appear as targets. Match the exact size you saw in lsblk.
8. Write the image and let it finish, including validation. Do not pull the drive early.
   Why: the OS caches writes; "100%" on the progress bar is not "safely on the disk." Etcher's post-write validation catches a bad write before you waste a boot attempt.
9. For the command-line route, the dd equivalent replaces steps 6 to 8 — but remember the wiki does not recommend it for beginners.
   Why: dd is transparent and scriptable, but it is also the famous "disk destroyer": there is no undo, so the of= target must be exactly right.

The command-line write, on Linux, for a stick at /dev/sdb:

# Decompress and write in one pipe (no intermediate .img needed)
gunzip -c batocera-x86_64-x86_64-43.1.img.gz | sudo dd of=/dev/sdb bs=4M status=progress conv=fsync

# Then flush and confirm
sync
echo "write complete"

Note of=/dev/sdb — the whole device, not /dev/sdb1 the partition. Writing to the partition produces a stick that will not boot. status=progress gives you a live byte counter; conv=fsync forces the write to complete before dd returns.

Steps 10 to 12: boot and expand

10. Move the flashed drive to the target machine and enter its boot menu. On a Framework 13, a Beelink Mini S12, and most mini PCs that key is F12; on others it is F8, F10, ESC, or DEL — the splash screen usually says.
    Why: you must tell the firmware to boot the USB device rather than the internal OS. The boot menu is the one-time override that does exactly that.
11. Disable Secure Boot in the BIOS/UEFI first if the USB does not appear or refuses to boot.
    Why: Batocera's bootloader is not signed with Microsoft's keys, so Secure Boot rejects it outright. This is the single most common "my USB won't boot" cause on modern hardware, and it gets its own section below.
12. Boot Batocera, let the first-run resize complete, and reach the EmulationStation menu.
    Why: on first boot Batocera expands its writable userdata partition to fill the drive and generates default configs. Interrupting this leaves you with a cramped partition and half-written settings. Let it finish; it takes under a minute.

That is the flash. If you are running live off the USB, you are done and can start adding games. If this machine is destined to be a permanent Batocera box, proceed to the internal-disk install below.

First Boot and Secure Boot

The gap between "flashed a stick" and "playing games" is almost always a firmware setting. Here is the firmware knowledge you need.

Secure Boot: why it must die

Secure Boot is a UEFI feature that only permits bootloaders signed by keys the firmware trusts — in practice, Microsoft's. Batocera's bootloader is not signed with those keys, so on a machine with Secure Boot enabled the flashed USB simply will not appear as bootable, or it throws a "Secure Boot violation" and refuses. The fix is to turn it off. On the Framework 13 and most modern boards the path is: enter setup (usually F2 or DEL at the splash), find the Security or Boot tab, set Secure Boot to Disabled, save, and exit. This is a documented, reversible setting — you can turn it back on if you later reinstall Windows — and it is a hard requirement, not a suggestion. If you take one thing from this entire tutorial, take this: Secure Boot off, or nothing boots.

Boot order and the F12 menu

There are two ways to boot the USB. The one-time boot menu — F12 on Framework and Beelink hardware — lets you pick the USB device for this boot only, leaving your normal boot order intact. This is the right choice for a live trial. The alternative is editing the persistent boot order in the BIOS to put USB first, which is convenient during install but which you will want to revert afterward so the machine boots its internal Batocera install directly. Either works; the one-time menu is less to remember to undo.

A note on legacy versus UEFI: Batocera's x86 image boots in UEFI mode on modern hardware, which is what you want. If your firmware has a "CSM" or "Legacy Boot" option, leaving it off (pure UEFI) is the cleanest configuration and avoids a whole class of dual-mode confusion.

The first-boot resize and EmulationStation

The first successful boot is slower than every boot after it, and that is by design. Batocera does two things on first run: it grows the writable userdata partition to consume the free space on the drive, and it writes out the default configuration tree. When it finishes you land in EmulationStation, the frontend, showing only the systems for which it found games — which, on a fresh install, may be just a couple of built-in homebrew titles. An empty-looking menu is not a failure; it means the OS is healthy and simply waiting for you to add ROMs. Where those go, and the config that ties it all together, is the back half of this guide.

Installing to Internal Disk

Running live off a USB stick is fine for a demo and miserable as a daily driver — USB flash storage is slow and wears out. For a permanent build, install to the machine's internal drive.

Live USB vs installed: know the difference

When you boot the flashed USB, you are running Batocera from the stick. Everything works, but performance is bottlenecked by USB throughput and the stick's endurance, and you are one accidental unplug away from a bad day. Installing to the internal SSD or NVMe copies the system to fast, permanent storage and frees the USB stick for reuse. The distinction trips up newcomers: the install option is not a separate download, it is a menu inside the live system you just booted. The official install guide on the Batocera wiki documents the same flow in full.

Install on a new disk: the menu path

From the running live system, the path is deliberate and short. Open the MAIN MENU (press Start or the menu button), go to SYSTEM SETTINGS, and choose INSTALL BATOCERA ON A NEW DISK — the "Install on a new disk" option called out in the official install notes. You select the target internal disk, confirm, and let it write. The rationale for doing it this way rather than cloning the USB: the installer lays down a fresh partition layout sized to the internal drive and marks it bootable correctly, which a naive clone does not.

MAIN MENU
  └─ SYSTEM SETTINGS
       └─ INSTALL BATOCERA ON A NEW DISK
            ├─ Target device:   [ nvme0n1  238 GB ]
            ├─ Architecture:    [ x86_64        ]
            └─ [ INSTALL ]   ← select, confirm, wait

This step erases the selected internal disk entirely. If that disk currently holds Windows or your files, they are gone. Choose the right target, and if the machine has multiple drives, know which is which before you confirm.

Framework 13 and Beelink Mini S12 specifics

Both machines the project names explicitly follow the identical flow, and both use F12 for the boot menu. On the Framework 13, remember Secure Boot lives in the BIOS you reach with F2 — disable it before you expect the USB to boot at all. On the Beelink Mini S12 and its many mini-PC cousins, the internal eMMC or NVMe is your install target; these boxes frequently ship with a Windows license you may or may not want to overwrite, so decide before you hit INSTALL. After the install completes, power off, remove the USB stick, and boot — the machine now comes up directly into Batocera from its internal disk, and the stick is free to reflash for the next box. If you are chasing the absolute cleanest hardware-accurate experience and find the whole emulation stack unsatisfying, that is a different philosophy entirely — the FPGA crowd building around boards like the MiSTer Multisystem 2 would tell you to skip software emulation altogether — but for breadth of library per dollar, an installed Batocera box is very hard to beat.

Common Pitfalls and Fixes

These are the failures that fill the forums, ranked roughly by how often they waste people's evenings. Each has a real cause and a real fix.

The image won't boot at all

Pitfall 1 — Secure Boot still enabled. The USB does not appear in the boot menu, or you get a Secure Boot violation. Fix: disable Secure Boot in the BIOS, as covered above. This is the number-one cause, full stop.

Pitfall 2 — a bad or incomplete flash. The drive boots to a GRUB prompt, a black screen, or a kernel panic. Fix: re-verify the SHA256 of the downloaded image, reflash with Etcher (and let it validate), and try a different, known-good USB port — front-panel headers and hubs are common culprits. If the checksum was wrong, redownload.

Pitfall 3 — wrote to the partition, not the device. A dd user who targeted /dev/sdb1 instead of /dev/sdb ends up with a non-bootable stick. Fix: reflash to the whole device node, with no partition number.

Controllers, keyboards, and the 43.1 fix

Pitfall 4 — your Xbox controller "types" instead of playing. This is the exact bug version 43 shipped: Microsoft controllers detected as keyboards. Fix: run 43.1, which corrects the detection. If you are stuck on 43 for some reason, update via the Butterfly channel rather than fighting the mapping by hand.

Pitfall 5 — lightgun or Dolphin options missing. LR-MAME lightguns and LR-Dolphin per-game options both regressed in 43. Fix: again, 43.1. These are not configuration problems; they are the reason the point release exists. Do not spend an hour in menus trying to fix a bug the project already fixed.

Games are there but won't launch

Pitfall 6 — ROMs in the wrong folder. Games dropped anywhere other than the correct per-system directory under userdata/roms simply will not appear. Fix: place each system's games in its exact folder — SNES in snes, Genesis in megadrive, and so on — then refresh the gamelist from START → GAME SETTINGS → UPDATE GAMELISTS. When in doubt about where a system's ROMs live and which extensions are accepted, the naming and folder discipline is the same one the wider ROM-management scene argues about; our breakdown of a 6,041-game handheld library walks through the exact folder-and-extension hygiene that keeps a collection legible.

Pitfall 7 — missing BIOS files. Systems like PlayStation, Saturn, and Neo Geo need specific BIOS files that Batocera cannot legally ship. A game launches, flashes black, and drops back to the menu. Fix: the built-in MISSING BIOS check (in the menu) lists exactly which files are absent and the checksums to match; supply them from your own hardware into userdata/bios. The Batocera add-games-and-BIOS wiki page and the libretro BIOS reference list the canonical filenames and hashes.

Pitfall 8 — TheXTech won't start. The Super Mario Bros. X engine needs current assets. Fix: 43.1 requires a minimum of asset version 1.3.7; update the engine's assets to that version or newer and it runs.

Troubleshooting Table

A scannable reference for the symptoms you are most likely to hit, and the fastest known fix for each. Start here before you post to a forum.

The quick-reference table

Reading the logs

When the table does not cover your symptom, the logs will. Batocera writes an EmulationStation log and per-emulator logs under userdata, and you can reach a shell to read them either from the on-screen terminal or over SSH — the service is enabled by default with user root and password linux. From a shell:

# See the last lines of the EmulationStation log
tail -n 40 /userdata/system/logs/es_launch_stdout.log

# System hardware and version summary
batocera-info

# Which emulator/core a game will use
batocera-config

The batocera-info command is your friend for confirming the machine actually sees the CPU, GPU, and memory you expect — a good sanity check when performance is worse than it has any right to be.

When to reflash vs when to fix

A rule of thumb that saves time: if the problem is booting or storage — won't boot, corrupt filesystem, tiny partition — reflash, because those live in the image and the partition table and are cheaper to recreate than to repair. If the problem is behavior — a controller, a core option, a missing BIOS, a resolution — fix it in place, because reflashing throws away your config and changes nothing about the bug. The whole point of Batocera's read-only-system / writable-userdata split is that these two classes of problem are separable. Use that.

Advanced Tips

Once it boots and plays, these are the moves that separate a working install from a good one.

Update channels: Stable vs Butterfly

Batocera has two update channels, and knowing the difference is how you got early access to 43.1's fixes. The Stable channel is the default and the conservative choice — it receives point releases like 43.1 soon after they are validated. The Butterfly channel is the faster-moving track where 43.1 was available immediately on release, ahead of Stable. If one of the 43 regressions is biting you and you cannot wait, switch to Butterfly to pull 43.1 now; if you value calm over immediacy, stay on Stable. You change channels in the UPDATES menu or in the config file, and you can update in place without reflashing:

# In batocera.conf
updates.enabled=1
updates.type=butterfly     # or: stable

# Then, from the menu: MAIN MENU → UPDATES → "START UPDATE"
# Or from a shell:
batocera-upgrade

Updating in place preserves your userdata — your games, saves, and settings all survive the upgrade. This is precisely why "I already installed 43" does not mean "I must reflash for 43.1." Point the channel at the release and upgrade.

Network share and scraping

Two features turn a bare install into a proper front-end. First, Batocera exposes its userdata tree as a network share — SMB by default — so from another computer you can browse to the box over the network and drag ROMs, BIOS files, and artwork straight into the right folders without ever touching the SD card. The share is reachable at \\BATOCERA\share on Windows or smb://BATOCERA.local/share on macOS and Linux; that share maps to /userdata, so ROMs go into share/roms and BIOS files into share/bios. Second, the built-in scraper pulls box art, metadata, and descriptions for your library; run it from the menu after adding games and the empty-looking grid becomes a proper visual catalog.

Overlays, bezels, and shaders

The cosmetic layer is where Batocera earns its keep on a big screen. Bezels (also called overlays) fill the black bars beside a 4:3 game on a 16:9 display with artwork of the original hardware; shaders emulate the look of a CRT — scanlines, phosphor glow, aperture grille — for people who find raw pixels too clean. Both are toggled globally or per-system, and both lean on the same RetroArch machinery underneath. If you want to understand the shader and core layer well enough to tune it rather than just cycle presets, the libretro project documents it exhaustively — the libretro docs are the canonical reference — and Batocera's menus map those concepts onto its own UI. Start with a CRT shader on the 8- and 16-bit systems and leave the 3D consoles clean; that is the configuration most people land on after a week of fiddling.

The Complete Configuration

Here is a known-good starting configuration and the directory knowledge to go with it. Everything lives in two files and one folder tree.

The batocera.conf that works

Nearly all global behavior is set in a single file: /userdata/system/batocera.conf. You can edit it over the network share or from a shell. This is a sane baseline for an installed x86 box — Wi-Fi on, SSH on, stable updates, a CRT shader on the retro systems, and controller-friendly defaults:

# /userdata/system/batocera.conf  — annotated baseline

## System
system.power.switch=PC              # standard ATX / mini-PC power
system.hostname=BATOCERA            # name on the network share
system.timezone=Europe/Paris        # set your own zone

## Updates
updates.enabled=1
updates.type=stable                 # butterfly for early point releases

## Network
wifi.enabled=1
wifi.ssid=YOUR_SSID
wifi.key=YOUR_WIFI_PASSWORD
system.ssh.enabled=1                # remote shell: root / linux

## Video (leave 'auto' unless you have a reason)
global.videomode=auto
global.bezel=default                # arcade-style overlays on 4:3 games

## Global emulator defaults
global.smooth=1                     # bilinear; 0 looks sharper, your call
global.shaderset=none               # per-system overrides below win
global.rewind=1                     # RetroArch rewind where supported
global.autosave=0                   # manual save states by default

## Per-system: CRT shaders on the classics, clean on 3D
snes.shaderset=scanlines
nes.shaderset=scanlines
megadrive.shaderset=scanlines
gb.shaderset=scanlines
n64.shaderset=none
dreamcast.shaderset=none
gamecube.shaderset=none

Change updates.type to butterfly if you want point releases the moment they drop; leave it stable for the quieter life. Every key here has a documented counterpart in the menus, so nothing in this file is a secret handshake — it is just faster to set ten things in a text file than to click through ten menus.

Directory layout you should know

The writable partition is /userdata, and its shape is worth memorizing because every "where does this go" question resolves to a folder in here:

/userdata
├── roms/            # games, one folder per system
│   ├── snes/        #   Super Nintendo
│   ├── megadrive/   #   Sega Genesis / Mega Drive
│   ├── psx/         #   PlayStation (needs BIOS)
│   ├── n64/         #   Nintendo 64
│   └── ...          #   one folder per supported system
├── bios/            # BIOS files you supply yourself
├── saves/           # in-game saves and save states
├── music/           # background music for the menu
├── screenshots/     # captured with the hotkey
├── decorations/     # bezels / overlays
├── shaders/         # custom shader presets
└── system/
    ├── batocera.conf    # the file above
    ├── configs/         # per-emulator configs
    └── logs/            # es_launch_stdout.log, etc.

Drop a SNES ROM into /userdata/roms/snes, a PS1 BIOS into /userdata/bios, refresh the gamelist, and it appears. That is the whole content model.

Backing it all up

Because system and data are separate, backing up Batocera means backing up /userdata and nothing else — the OS you can always reflash from the download page. A periodic copy of that tree to another machine, over the network share, is the entire disaster-recovery plan. Save states, controller mappings, scraped art, and your batocera.conf all live in there; preserve it and a catastrophic SD-card failure becomes a thirty-minute reflash rather than a lost library.

# From another Linux/macOS machine, pull a full userdata backup over SSH
rsync -av --progress root@batocera.local:/userdata/ ./batocera-backup/
# password: linux   (change it if the box lives on an untrusted network)

Flash the image, restore userdata, and you are exactly where you were. That resilience — not the emulator count, not the shader eye-candy — is the quiet reason Batocera has outlasted a decade of flashier competitors since 2016. Download it, verify it, flash it, and it will be running long after the mini PC's warranty has expired.