Batocera 43.1 Download: 12 Steps, 30-Min Setup

There is a specific kind of email I get about Batocera, and it always opens the same way: "I downloaded Batocera and ran the file and nothing happened." Nothing happened because there is no file to run. Batocera is not a program you launch inside Windows. It is a Linux operating system that seizes an entire disk, installs a boot menu of two-hundred-plus emulators, and never asks your existing OS for permission because it never boots your existing OS at all. Internalising that one sentence is the difference between a working arcade cabinet and a forum post titled "HELP nothing works."

This tutorial covers the Batocera 43.1 "Glasswing" download and install end to end. It is the current stable point release in the 43 series, built 30 May 2026, carrying the image stamp 20260530. Twelve numbered steps, each with the reason it exists, because a step without a rationale is just cargo-culting someone else's YouTube video. Budget roughly thirty minutes from download to a booted, secured, network-visible machine, in line with the project's own twelve-step onboarding. Longer if your CPU is older than you think it is, which happens to be the first trap and the reason the Prerequisites section below is not optional reading.

Batocera is free, it is open source, and it will outlast whichever handheld you were about to overpay for. If your goal is a curated pocket device instead of a PC install, that is a different article — see the debate over whether a Miyoo Mini Plus and its imaginary 6,041-game list is worth the drawer space. But if you have a mini PC, an old laptop, or a Raspberry Pi gathering dust, keep reading. This is the download that turns it into an emulation station.

What Glasswing Actually Is

Before you download anything, you need an accurate mental model of what you are downloading. Batocera is not RetroPie, it is not a launcher, and it is not a "mod." It is a self-contained, immutable Linux distribution whose entire personality is EmulationStation and a stack of emulators. Get the model right and every later step makes sense.

The release, in one paragraph

Batocera 43.1 is the current stable image, the "Glasswing" line, cut on 30 May 2026. It ships with over 200 preconfigured emulator cores, spanning everything from the Nintendo Entertainment System up through PlayStation 2 and Sega Dreamcast, all wired into a single controller-driven front end so you never touch a config file to play a game. The word "preconfigured" is doing real work there: on a bare RetroArch install you would spend an afternoon assigning cores per system, an ordeal I have documented in the RetroArch cores walkthrough. Batocera has already made those decisions for you, sensibly, out of the box.

The project is built and maintained by the batocera-linux community, with the full source tree hosted on GitHub at batocera-linux/batocera.linux. It is a Buildroot-based distribution — the same embedded-Linux toolchain that underpins Lakka — which is why it boots in seconds and why you cannot apt install anything onto it. It is not Debian. The read-only system image is a feature, not a limitation, and it is the reason a few later steps look strange if you are used to a normal desktop.

Free means free — and the 2.49€ footnote

Batocera costs zero. No licence fee, no subscription, no "pro" tier, no mandatory donation, no nag screen. The download at the official source is the whole product. Anyone telling you otherwise is either confused or selling something.

Which brings us to the footnote. A Spanish community portal, batocera.es, sells access to a private support forum for 2.49€ a year. That is their prerogative and it is a fine way to fund a fan site, but be precise about what changes hands: you are paying a third party for a forum login, not for Batocera. The operating system itself remains free whether you pay that 2.49€ or not. Do not conflate a community's paywalled help desk with the licence of the software, because they have nothing to do with each other.

It replaces your boot; it does not sit on top of Windows

Here is the sentence from the intro, expanded, because it is the single most misunderstood fact about this distro. Batocera boots directly from a USB stick or SD card and replaces the host operating system's boot process entirely. It does not install "on top of" Windows. It does not dual-boot automatically. When Batocera is running, Windows is not running — the machine has handed control to a different operating system living on a different disk. You can absolutely keep Windows on your internal SSD and run Batocera from a USB stick that you unplug afterwards; that is arguably the cleanest way to try it. But the two do not coexist inside one boot. They take turns, and you choose who goes next in your firmware boot menu.

This is also why "I downloaded it and nothing happened" is inevitable. There is nothing to double-click. The .img.gz you download is a disk image, a byte-for-byte picture of a bootable medium, and it only becomes useful once it is written to a stick with a flashing tool. We will do exactly that in Steps 3 through 6.

Prerequisites & the x86_64-v3 Trap

Two things sink first-time installs before they start: not enough storage, and a CPU too old to run the modern x86_64 image. Both are cheap to check and expensive to ignore. Read this section before you touch the download page.

Hardware: the storage and silicon minimums

The medium you flash to must be at least 8 GB, which is the hard minimum for the installation. In practice, use 16 GB or larger. The extra headroom is not vanity; Batocera downloads its own updates and decoration packs into free space, and a 16 GB target is what lets the auto-update path work without wedging itself. An 8 GB stick will install and boot, but you will feel the ceiling the first time you try to update or add a bezel pack.

For the machine itself, the realistic list looks like this:

• A 64-bit x86 PC or mini PC — this is the most common and best-supported target, and the one this guide assumes. Mini PCs (the N100-class boxes, old Intel NUCs, thin clients) are the single most-tutorialised Batocera platform of 2026 for a reason: they are cheap, silent, and boot Batocera without drama.
• A Raspberry Pi — Pi 4, Pi 400, or Pi 5 all have dedicated images. A Pi is a fine 8-bit-through-PS1 machine and a frustrating PS2 one.
• A spare USB 3.0 stick or SD card, 16 GB+, that you are willing to erase completely.
• A second computer to do the flashing, and to copy your legally-obtained ROMs over the network afterward.

If your ambition is Dreamcast, PSP, and the lighter end of PS2, a modern mini PC is the sweet spot. If you want a handheld, Batocera runs on some, but you may be happier with purpose-built hardware — the Retroid Pocket 6 versus 5 comparison covers what that silicon actually delivers versus a repurposed PC.

The x86_64-v3 microarchitecture trap

This is the one that eats an evening. Batocera's modern x86_64 image is compiled against the x86_64-v3 microarchitecture baseline — roughly the AVX2-class instruction set that arrived with Intel's Haswell (2013) and AMD's Excavator/Zen. If your CPU predates that — a 2011 Sandy Bridge laptop, an early Core 2, a first-generation Core i-series — the current image may simply refuse to boot, and it will do so silently: black screen, no error, no clue. Newcomers reflash three times, blame the USB stick, and post screenshots of nothing.

The fix is diagnosis, not persistence. If a machine is older than about 2013 on Intel or 2015 on AMD, check its CPU against the x86_64-v3 requirement before assuming the flash failed. Genuinely ancient hardware is not out of luck — older Batocera releases targeted a looser baseline — but the current "Glasswing" x86_64 image expects modern-ish silicon. Confirm your architecture support against the official Batocera install wiki before you spend money on a USB stick to run it.

Software you need before you download

You need exactly one thing: a tool that writes a compressed disk image to removable media. The three the project itself points at are:

• Raspberry Pi Imager (available from raspberrypi.com/software) — despite the name, it flashes any custom image on Windows, macOS, and Linux, and it decompresses .img.gz transparently. In 2026 this is my default recommendation for beginners because it is hard to misuse.
• balenaEtcher (from etcher.balena.io) — the old standby, cross-platform, also handles .img.gz without a manual unzip.
• USBImager — a tiny, no-frills alternative if you want something that starts in under a second and does one job.

Linux users with a terminal habit can skip all three and use dd, which we will cover, along with the disclaimer it deserves. You do not need to unzip the download first; every tool on this list reads the .gz directly. Unzipping first is a classic wasted step that also doubles your disk usage for no reason.

Steps 1-2: Pick the Image for Your Silicon

With the model and the prerequisites straight, the actual procedure begins. Here is the whole thing at a glance, then we elaborate each phase with commands and expected output.

The twelve steps, compressed

1. Confirm your CPU meets the x86_64-v3 baseline (AVX2-class, ~Haswell/Excavator or newer). Rationale: the 43.x x86_64 image will not boot on older silicon, and it fails without an error message.
2. Download the image matching your architecture from batocera.org/download, via a mirror. Rationale: the main server is volunteer bandwidth, and a wrong-architecture image boots to a black screen.
3. Verify the download's integrity before flashing. Rationale: a truncated .img.gz flashes a system that fails at random and wastes an hour of your life.
4. Flash the .img.gz directly to a 16 GB (8 GB minimum) stick or SD card. Rationale: the flasher decompresses on the fly, so you never unzip first.
5. Confirm you targeted the removable disk, not your system SSD. Rationale: flashing is destructive and irreversible; there is no undo.
6. Set the target machine's firmware to boot from USB/SD and disable Secure Boot if it blocks the handoff. Rationale: Batocera replaces the boot process, so the firmware must be willing to hand off to it.
7. Boot Batocera and let the first-run resize finish before you touch anything. Rationale: it expands the SHARE partition to fill the medium, and interrupting that corrupts userdata.
8. Set a persistent root password via System Settings → Security. Rationale: the default login is root / linux on a read-only image, and a plain passwd will not stick.
9. Connect networking and note the SMB share at \\BATOCERA. Rationale: that share is how you move ROMs and BIOS onto the machine without ever reflashing.
10. Copy ROMs into /userdata/roms/[system]/. Rationale: Batocera ships zero games, and the folder name is what maps a file to the correct emulator.
11. Supply BIOS files you legally dumped into /userdata/bios/ and verify them in the web UI. Rationale: several cores refuse to launch without the exact, checksum-matched BIOS.
12. Configure updates (stable vs butterfly) and back up /userdata. Rationale: online updates are one menu away, but your saves and configs are not shipped with the OS and vanish with the card.

Reading the filename

Go to the one canonical source: batocera.org/download. Everything else — random file lockers, "modded" ISOs, torrent bundles with games baked in — is either out of date or actively hostile. The download page presents images named to a strict, legible pattern:

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

# The 43.1 x86_64 release, concretely:
batocera-x86_64-43.1-20260530.img.gz

Decode it left to right. batocera is the product. x86_64 is the architecture — standard 64-bit PCs and mini PCs. 43.1 is the version. 20260530 is the build date, 30 May 2026, which is how you confirm at a glance you grabbed Glasswing and not a stale cached copy. The .img.gz suffix means it is a gzip-compressed raw disk image. That filename is a small act of engineering courtesy; respect it by reading it before you flash.

x86_64, Raspberry Pi, Rockchip — and the mirrors

Pick the architecture that matches your hardware, because this is the wrong-image trap. x86_64 covers the overwhelming majority of PCs, mini PCs, old laptops, and handheld PCs. Raspberry Pi boards each have their own image (the Pi 5 and Pi 4 are distinct builds). Various Rockchip single-board computers — the RK3588 and RK3399 boards — have dedicated images too. Flash an ARM Pi image to an x86 PC and you get the black screen of confusion; the file is not "corrupt," it is simply speaking a different instruction set.

Two practical notes. First, the download page lists regional mirror servers. If the primary server on batocera.org is crawling, switch to a mirror — the links are right there on the page. The main host is a volunteer project's bandwidth, not a CDN with your name on it, so a slow download is a reason to change mirrors, not to blame your ISP. Second, if you are weighing Batocera against the Debian-based alternative on a Pi, note that RetroPie has its own release cadence quirks — the situation is laid out in the RetroPie PC image status for 2026. Batocera's clean, dated image list is, frankly, one of its quiet advantages.

Steps 3-6: Verify, Flash, Don't Nuke Your SSD

Now the medium gets written. This is the part with genuine consequences: pointing a flasher at the wrong disk erases it, and no dialog box will save you. Slow down for exactly the length of this section.

Verify the download first

A half-downloaded image is worse than no image, because it flashes cleanly and then fails hours later when a specific block turns out to be garbage. Before flashing, compute a checksum of the file you downloaded and compare it against the value published alongside the image or its mirror. On Linux or macOS:

$ sha256sum batocera-x86_64-43.1-20260530.img.gz

3f9c1b0e7a52d4c8e1f6a9b3c7d0e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6  batocera-x86_64-43.1-20260530.img.gz

On Windows, CertUtil -hashfile batocera-x86_64-43.1-20260530.img.gz SHA256 does the same job. The exact hash above is illustrative — the point is the procedure: if the string you compute does not match the published one, the file is damaged, and you re-download (from a different mirror) rather than flash. Thirty seconds here saves the multi-reflash death spiral later.

Flashing with Raspberry Pi Imager or Etcher

The graphical path is deliberately boring. In Raspberry Pi Imager: choose "Use custom," select your batocera-x86_64-43.1-20260530.img.gz, choose your USB stick as the storage target, and write. In balenaEtcher: "Flash from file," pick the same .img.gz, select the target, flash. Neither tool needs you to decompress anything; both read the gzip directly. Both also try to stop you from selecting an internal system drive, which is the one safety net you should not rely on but will quietly appreciate.

When it finishes and verifies, you are done with this step. Do not "eject and reformat" the stick when Windows pops up its inevitable "you need to format this disk" dialog after flashing — that dialog appears because Windows cannot read Batocera's Linux partitions, not because anything is wrong. Click Cancel. Formatting there undoes the flash.

The dd path, and how to not lose a disk

If you live in a terminal, dd is the direct route — and it is nicknamed "disk destroyer" because it does precisely what you tell it, including erasing the wrong disk without a flicker of hesitation. The non-negotiable first move is to identify your target unambiguously. On Linux:

$ lsblk

NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
sda      8:0    0 476.9G  0 disk
├─sda1   8:1    0   512M  0 part /boot/efi
└─sda2   8:2    0 476.4G  0 part /            <- your system SSD. DO NOT TOUCH.
sdb      8:16   1  28.9G  0 disk                <- the 32GB USB stick = your target

Read that output like your data depends on it, because it does. The RM column (1 = removable) and the size are your confirmation: sdb, 28.9 GB, removable, is the stick. sda, 476 GB, mounted at /, is the machine you are typing on. Then, and only then:

# Replace sdX with your VERIFIED target device (e.g. sdb).
# Write to the whole disk (sdb), not a partition (sdb1).

$ zcat batocera-x86_64-43.1-20260530.img.gz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync

4194304+0 records in
4194304+0 records out
8589934592 bytes (8.6 GB) copied, 214.6 s, 40.0 MB/s

The zcat ... | dd pipe decompresses and writes in one pass, so again there is no separate unzip. status=progress gives you a live byte count, and conv=fsync forces the data to physically hit the medium before dd returns, so you do not yank a stick that is secretly still buffering. When the record counts print, the flash is complete. Eject cleanly and move to the target machine.

Steps 7-9: First Boot, Resize, Security

Plug the stick into the target machine, enter its firmware boot menu (usually F12, F11, F8, or Esc during POST — it varies by vendor), and select the USB device. If nothing happens, that is a firmware problem, not a Batocera one, and the Troubleshooting table below has the fix. Assuming it boots, three things happen in order, and the first one you must not interrupt.

What the first boot does (and the df -h proof)

On its very first boot, Batocera automatically resizes the SHARE (userdata) partition to fill the entire medium. If you flashed an 8.6 GB image onto a 256 GB SSD, the boot process grows the data partition to reclaim all that unused space. This takes a moment and it must be allowed to finish — pulling power or the stick mid-resize corrupts the very partition your saves and ROMs will live on. Let it reach EmulationStation before you do anything.

Once you are at the main menu, you can confirm the resize worked. Enable SSH (it is on by default on most builds) and connect, or open a terminal, and check the filesystem table:

$ df -h

Filesystem      Size  Used Avail Use% Mounted on
overlay          98M   44M   54M  45% /
/dev/sda1       2.0G  1.4G  600M  71% /boot
/dev/sda2       228G  1.3G  227G   1% /userdata

There is the proof. /userdata has expanded to 228 GB on a 256 GB drive, while the read-only system lives in a tiny 98 MB overlay mounted at /. That split — immutable OS, huge writable userdata — is Batocera's whole architecture in three lines. Everything you add goes under /userdata; the system image is sealed.

Change the root password the right way

Batocera's default credentials are, and have long been, root / linux. This is documented, not secret, which means every port scanner on your network already knows it too. On a machine that is about to sit on your LAN sharing files, that is a door you close on day one.

Here is the trap: you cannot just run passwd. The system partition is a read-only squashfs, so a password set with passwd evaporates on the next reboot. The persistent path is the menu: Main Menu → System Settings → Security, where "Enforce security" lets you set a root password that Batocera writes to the writable SHARE partition and re-applies on every boot. That is also where you can disable the web UI or SSH if you would rather they not listen at all. Set the password, note it somewhere real, and move on. This single menu is the difference between a hobby appliance and an open relay.

Networking and the \\BATOCERA share

Get the machine online — Ethernet is painless, Wi-Fi is under Network settings — because the network is how ROMs get on board. Batocera exposes an SMB (Windows) file share automatically. From another computer:

# Windows Explorer address bar:
\\BATOCERA

# macOS Finder (Cmd+K):
smb://batocera/

# Linux, or to poke around over SSH:
$ ssh root@batocera        # password: whatever you just set in the Security menu
$ ls /userdata/roms
$ ls /userdata/bios

Opening \\BATOCERA reveals the shared folders — roms, bios, saves, and the rest of /userdata — as ordinary network drives you can drag files into. Whether the SHARE partition is exFAT or ext4 determines whether Windows can read the card directly when plugged in, but the network share works regardless of filesystem, which is why it is the method I always recommend. With the share visible, the OS install is effectively done. What remains is content, and content is where the law lives.

Steps 10-12: ROMs, BIOS, and the Legal Part

Batocera ships no games and no BIOS files. This is not an oversight or a missing feature to be patched. It is the deliberate legal firewall that lets an open-source project distribute freely without a cease-and-desist in its inbox. You supply the content, from media you legally own.

Where files live under /userdata

The folder layout is rigid and self-documenting. ROMs go into /userdata/roms/, one subfolder per system, and the subfolder name is what tells Batocera which emulator to use. A NES game goes in /userdata/roms/nes/; a Genesis game in /userdata/roms/megadrive/; a PlayStation disc image in /userdata/roms/psx/. Put a file in the wrong folder and it either will not appear or will launch under the wrong core. After copying files in, either reboot or trigger Main Menu → Game Settings → Update Gamelists so EmulationStation rescans and the titles show up.

Where do legally-clean ROMs come from? The defensible answer is your own cartridges and discs, dumped with dedicated hardware. That is a whole discipline of its own — the Retrode cartridge-dumping walkthrough covers reading SNES and Genesis carts to files you then drop straight into /userdata/roms/. Batocera stays clean by shipping nothing; you stay clean by only feeding it backups of media you own.

The BIOS problem

Several systems will not emulate at all without their original BIOS — a copyrighted firmware dump the project cannot and does not include. BIOS files go into /userdata/bios/ (some cores want a subfolder), and the emulator matches them by exact filename and, often, exact checksum. Get the byte-for-byte-wrong file and the core silently refuses to boot. Here is the common shortlist:

To confirm your BIOS files are correct rather than merely present, use the web interface. Point a browser at http://batocera/ (or the device's IP) and open the BIOS section: it lists every required file per system with a red/green status and MD5 verification. That MD5 check is the honest way to know a file is the right one — the checksums themselves are published on the Batocera wiki, so you can validate a dump you made yourself without ever downloading someone else's. If a file shows red, it is the wrong revision or corrupt, and the emulator will treat it as absent.

Scraping metadata without a ban

With games in place, the last cosmetic step is scraping — pulling box art, descriptions, and metadata so your library looks like a shelf instead of a directory listing. Batocera's built-in scraper lives under Main Menu → Scraper. Use it in moderate batches. Hammering a free metadata provider with ten thousand requests at once is how you earn a temporary rate-limit and a wall of "scrape failed" messages that people mistake for a bug. Scrape a few systems at a time, let it breathe, and it works. This step is optional; a game plays exactly the same whether or not it has a cover, and the curation obsessives already know curation is a rabbit hole — see the argument over whether a headline game count means anything at all.

Updating Without Reflashing

You flashed once. You should rarely need to flash again, because Batocera updates itself in place. Understanding the two channels — and when to ignore them and reflash — keeps a working system working.

Online updates: stable vs butterfly

The normal update path is entirely in the menu: Main Menu → Updates & Downloads → Updates, where you can check for and start an online update. (Spanish-language guides render this navigation as Menú del sistema → Actualización; it is the same screen, just localised.) The system downloads the newer image and applies it on the next reboot, preserving your /userdata — your ROMs, saves, and configs survive.

There are two channels. Stable is what you want: tested point releases like 43.1. Butterfly is the beta/nightly channel, fresher and correspondingly more likely to break something you cared about. If you do not have a specific reason to be on butterfly, stay on stable. You can pin the channel in batocera.conf with updates.type=stable, which we do in the full config at the end.

Manual update packages

If your machine is offline or the in-menu update misbehaves, you can update manually by downloading the Batocera 43 update package from the official site and applying it — the same mechanism, just fed a file instead of a URL. This is the path for a media box that lives on an isolated network, or for anyone who prefers to grab the update on a laptop, checksum it, and carry it over. The result is identical to the online path: newer system image, untouched userdata.

When to reflash instead

In-place updates are convenient but not sacred. Cross a major version boundary — not 43.0 to 43.1, but the jump between major releases where the underlying base changes — and a clean reflash is often the calmer choice than a chain of in-place upgrades that have accreted quirks. The move is simple because of the architecture: back up /userdata to another disk, flash the new image fresh, restore /userdata. Since your entire library, saves, and configuration live in that one folder tree, a full reinstall costs you nothing but the copy time. That separation of immutable OS from portable userdata is Batocera's best trick, and it is worth exploiting deliberately once a year.

Common Pitfalls & Fixes

Every one of these lands in my inbox monthly. None is exotic. All are avoidable if you read the step that warns about them, which people do not, which is why this section exists.

Flash and boot mistakes

Pitfall 1: Unzipping the .img.gz first. Newcomers extract the archive, get a bare .img, and flash that — wasting time and disk. Fix: flash the .img.gz directly. Raspberry Pi Imager, Etcher, USBImager, and the zcat | dd pipe all decompress on the fly.

Pitfall 2: Flashing the wrong disk. The single most expensive mistake, because it erases real data. Fix: verify the target with lsblk (Linux) or Disk Management/diskpart (Windows) before you write, matching by size and removable flag. If two disks are the same size, unplug the one you are not flashing.

Pitfall 3: The machine ignores the USB stick. Firmware boots straight into Windows and never offers Batocera. Fix: enter the firmware boot menu (F12/F11/Esc at POST), enable USB booting, and — critically — disable Secure Boot, which blocks unsigned boot loaders like Batocera's. Set the USB device above the internal drive in boot priority if you want it to prefer the stick when present.

Config and controller traps

Pitfall 4: Root password reverts to "linux" after every reboot. You used passwd, which does not persist on a read-only image. Fix: set the password through System Settings → Security, which writes it to the SHARE partition and re-applies it on boot.

Pitfall 5: Games do not appear after copying them. Files landed in the wrong folder, or EmulationStation has not rescanned. Fix: confirm each game is under /userdata/roms/[system]/ with the correct system folder name, then run Game Settings → Update Gamelists or reboot.

Pitfall 6: Controller does nothing, or maps wrong. The pad has no stored mapping. Fix: hold a button at the input screen to begin configuration, or go to Main Menu → Controllers and configure/associate it. Update the controller database if a modern pad is unrecognised.

Expectation traps

Pitfall 7: Expecting games or BIOS in the box. Batocera ships neither, on purpose. Fix: supply ROMs and BIOS you legally own, place them under /userdata, and verify BIOS via the web UI's MD5 check. This is a feature of the licence, not a defect of the download.

Pitfall 8: Assuming it installs alongside Windows. Batocera replaces the boot; it does not layer onto an existing OS. Fix: run it from a USB stick you unplug afterward, or install it to a dedicated disk. If you want true dual-boot, that is a manual bootloader project, not a Batocera setting.

Pitfall 9: Ancient CPU, silent black screen. A pre-x86_64-v3 processor cannot run the current image. Fix: confirm the CPU against the AVX2/Haswell-era baseline; if it is too old, an earlier Batocera release with a looser target is your route, not a fourth reflash of the same stick.

Troubleshooting Table

When something breaks, resist the urge to reflash reflexively. Match the symptom to a cause first. Reflashing is the correct fix for perhaps two rows in this table and a waste of time for the rest.

Symptom, cause, fix

Reading the logs

When the table is not enough, Batocera keeps logs in one place, and they are readable over SSH or via the share. The launch logs in particular tell you exactly why an emulator bailed:

$ ls /userdata/system/logs/
es_log.txt              # EmulationStation itself
es_launch_stdout.log    # last game launch, standard output
es_launch_stderr.log    # last game launch, errors <- read this one first

# Tail the launch error log after a failed start:
$ tail -n 40 /userdata/system/logs/es_launch_stderr.log

Nine times out of ten, a game that "just closes instantly" has written the reason — missing BIOS, unsupported ROM format, a core that needs a setting — into es_launch_stderr.log. Read the log before you post the question. The answer is usually already there in plain English.

Advanced Tips

Once the basics boot, Batocera rewards tinkering. The layered override system, in particular, lets you tune one game without disturbing the other two thousand. If you came from hand-editing RetroArch, this will feel like a promotion.

Per-system and per-game overrides

Batocera regenerates retroarch.cfg on every boot from its own templates, so editing that file directly is pointless — your changes vanish. The persistent path is a custom overlay file that Batocera merges on top of the generated config:

# /userdata/system/configs/retroarch/retroarchcustom.cfg
# Persistent RetroArch overrides, merged over the generated retroarch.cfg

video_smooth = "false"
rewind_enable = "false"
fps_show = "false"
menu_driver = "ozone"

Settings cascade in a clear order of precedence: per-game → per-folder → per-system → global. A tweak scoped to one game beats the system default, which beats the global default. That means you can force integer scaling on a single fussy shmup, or a specific core for one N64 title that the default core mangles, while leaving everything else alone. Confirm exact keys and scopes against the libretro / RetroArch documentation, which is the upstream source of truth for every core-level option Batocera exposes.

Installing to an internal disk

Running from USB is great for trials and terrible for a permanent living-room box — the stick is slow and easy to knock loose. When you are committed, install Batocera to an internal SSD. Boot from the USB stick as usual, then use Main Menu → System Settings → Install Batocera on a new disk (or the batocera-install tooling from a terminal), pick the internal drive, and let it write itself down. The internal install is faster to boot, resizes userdata across the whole SSD, and frees your stick. Just be certain the target disk holds nothing you want — installing is the same destructive write as flashing, aimed at your internal drive this time.

RetroAchievements, netplay, and decorations

Three features worth turning on once the library is stable. RetroAchievements adds trophy-style challenges to supported games; enable it in Game Settings (or via global.retroachievements=1 plus your credentials) and pick whether you want hardcore mode, which disables save states and rewind for "legitimate" unlocks. Netplay lets you host or join online sessions on netplay-capable cores — latency-dependent, but genuinely fun for two-player 16-bit. Decorations (bezels and overlays, including The Bezel Project pack) fill the black bars around 4:3 content with tasteful artwork instead of void; install a pack via Updates & Downloads, then set global.bezel. None of these are necessary. All of them are why people keep opening the front end after the novelty of "it boots" wears off.

A Complete, Working batocera.conf

Everything above compresses into one file. /userdata/system/batocera.conf is the master configuration — a plain key=value text file that Batocera reads on boot. Here is an annotated, working starting point you can adapt, edit over the network share, and grow into.

The annotated config

## /userdata/system/batocera.conf  --  Batocera 43.1 "Glasswing"
## Lines starting with ## are comments. One key=value per line.

## --- Networking ---
wifi.enabled=1
wifi.ssid=YOUR_SSID
wifi.key=YOUR_WIFI_PASSWORD

## --- System / updates ---
system.hostname=BATOCERA
system.language=en_US
system.timezone=Europe/Madrid
updates.enabled=1
updates.type=stable          ## stable, not butterfly, unless you like breakage

## --- Global emulator defaults ---
global.videomode=default
global.smooth=1              ## bilinear filtering; set 0 for sharp pixels
global.rewind=0              ## rewind costs performance; on only where wanted
global.integerscale=0
global.ratio=auto
global.shaderset=none

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

## --- Per-system core / emulator selection ---
nes.core=fceumm
snes.core=snes9x
megadrive.core=genesisplusgx
gba.core=mgba
n64.emulator=libretro
n64.core=mupen64plus-next    ## if a title misbehaves, parallel_n64 is the fallback
psx.core=swanstation
psx.ratio=4/3

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

Two notes on the choices. The n64.core line uses the default mupen64plus-next, but a handful of N64 titles regressed on it in 2025, and parallel_n64 is the safer swap for those — the same core-picking logic I lay out in the RetroArch cores guide. Confirm current core names on the wiki before pasting, since they occasionally get renamed between releases.

Applying it and checking it took

Edit batocera.conf over the SMB share or SSH, then either reboot or reload settings. To confirm a key actually applied, Batocera ships helper commands that read and write the config without you re-parsing the file by eye:

$ batocera-settings-get updates.type
stable

$ batocera-settings-get snes.core
snes9x

# And to set a key from the terminal instead of editing the file:
$ batocera-settings-set global.smooth 0

If batocera-settings-get echoes the value you expect, the config is live. If it returns nothing, you either misspelled the key or the file did not save — check for a stray space around the =, which is the usual culprit.

Where to go from here

You now have a booted, secured, networked, updatable Batocera 43.1 install with a real config behind it. The thirty-minute clock the project quotes was honest: most of that half hour was reading, verifying, and not nuking your SSD, and precisely none of it required paying anyone. Keep the canonical references bookmarked — the download page for images and mirrors, the Batocera wiki for BIOS checksums and per-system quirks, the GitHub repository for what is actually changing under the hood, and the libretro docs when you graduate to core-level tuning. Back up /userdata before every major update, and Batocera will quietly do exactly what you asked for years. That is more than most software you pay for can claim.