Batocera Download 2026: 43.1 in 12 Steps, 30 Min

Let us kill the first misconception before it costs you an afternoon. A Batocera download is not a store page, not a launcher, and not a $39.99 SKU with a lifetime-license upsell buried in the checkout. It is a single compressed disk image — roughly 3 GB zipped, about 8 GB once it lands on your card — that you write to an SD card or USB stick and boot. The entire operating system, all 200-plus emulated systems, the menu, the scraper, the network share: one file. You do not install Batocera the way you install Windows. You flash it, the way you would flash a router or a Raspberry Pi.

The current stable release is 43.1, published 2026-05-30 as a point-release bug-fix on top of Batocera 43 "Glasswing," which shipped 2026-05-08. If a page tells you the latest version is a four-digit year code, or calls 43.1 "Glasswing," or offers you a "premium mirror" for nine dollars — close the tab. Those are content farms, and the retro-handheld corner of the web is thick with them. The only download that matters comes from batocera.org/download, which as of this writing labels the file exactly: "Get Batocera.linux 43.1."

This guide is twelve numbered steps, from empty card to first game, with the reasoning attached to each so you know why and not merely which button. It covers choosing the right architecture (the single most common way to brick a first attempt), verifying the archive, flashing with the tool the wiki actually recommends, expanding storage, loading ROMs over the network without touching the card again, and updating — or downgrading — from the command line. Budget about 30 minutes for the full flash-to-organized workflow. The download itself is the fast part; the organizing is where the time goes.

What You're Actually Downloading

Before you click anything, understand the object. People treat "Batocera download" as a verb aimed at a program. It is not. It is a request for an entire, self-contained Linux operating system that happens to boot straight into a game menu. Getting that mental model right is the difference between a clean install and three hours of confusion about why there is no .exe.

A 3 GB image, not an app

The file you are after is a raw disk image compressed with gzip, named on the pattern batocera-(arch)-(version)-(date).img.gz. For the x86_64 build of 43.1 that resolves to a filename like batocera-x86_64-43-20260530.img.gz — the exact version and date tokens are stamped by the build system — and it weighs in around 3 GB compressed. Write it to media and it expands to roughly 8 GB of real data, then grows further on first boot as the userdata partition claims the rest of the card. This is not a program you double-click inside another operating system. It is the operating system: a purpose-built distribution running kernel 6.15.11 in this release, compiled against LLVM 19.1.7, that boots to EmulationStation and does exactly one job.

200-plus systems in one file

Inside that single image is everything: the EmulationStation front end, the RetroArch runtime and its libretro cores, standalone emulators for the heavy systems, the scraper that pulls box art, the Wi-Fi stack, the SMB server that exposes your ROM folders to the network. Batocera 43 "Glasswing" headlined a graphics-stack overhaul — a Wayland session under the LabWC compositor on the AMD and Intel x86_64-v3 image, with Nvidia support still flagged experimental — but from the user's chair the point is simpler: you download once and you get the whole console-emulation stack, not a base you then assemble. If you have ever wrangled a software emulation setup piece by piece, or weighed it against a hardware approach like the MiSTer Multisystem 2 and its FPGA cores, the appeal of one file that already contains all 200-plus systems is obvious.

The license, and the price

The price is zero. Not "free trial," not "free tier," not "free with account." Batocera is released under Creative Commons BY-NC-SA, copyright 2016 through 2026 by the project, and the source lives in the open at github.com/batocera-linux/batocera.linux, where you can read the changelog commits and confirm the release cadence yourself. The only money involved is the cost of an SD card. Any site charging you for the image, or gating the "real" download behind a survey or a shortened link, is either running ads on stolen bandwidth or shipping you something you do not want on your card. For background context on how this fits the broader Linux-gaming and retro-handheld boom that outlets like Ars Technica and Engadget have covered at length, and for the neutral encyclopedia framing of console emulation generally, Wikipedia's emulator overview is a reasonable starting point — but for any Batocera-specific fact, go to the project's own pages, not the aggregators.

The Version Map: 43, 43.1, Glasswing

Version confusion is the number-one way people download the wrong thing, and the content farms exploit it deliberately by inventing version numbers that sound plausible. Here is the actual map, cross-checkable against the official changelog and DistroWatch.

43 "Glasswing" (May 8) versus 43.1 (May 30)

Batocera 43, codenamed "Glasswing," shipped on 2026-05-08. Three weeks later, on 2026-05-30, the project pushed 43.1 — a point release that is a pure stability pass, not a feature drop. Do not call 43.1 "Glasswing"; the codename belongs to 43, and 43.1 is the unglamorous bug-fix that makes 43 usable. What 43.1 actually fixed, per the official changelog, is a tidy list of 43.0 embarrassments: EmulationStation dropping systems and making collections disappear, LR-Dolphin's options menu breaking, Steam and flatpak launching failures, a stray Apple II GS removal in MAME, LR-MAME light-gun input breaking, Microsoft controllers being mis-detected as keyboards, and the storage manager ignoring certain partitions. If you are downloading fresh in 2026, you want 43.1 specifically, because it repairs exactly the things that would otherwise send you to a troubleshooting forum on day one.

Numbered, not year-based

Batocera versioning is sequential, not calendar-based. There is no "Batocera 2026"; there is 42, then 43, then 43.1, then eventually 44. This trips up readers conditioned by year-stamped software, and it is precisely the gap the farms fill with fake "Batocera 2026 Edition" pages. The immediately previous major was 42 "Papilio," released 2025-10-12, which remains the upgrade baseline many 2026 guides reference and the version you would pin to if 43 broke something you depend on. For lineage and release-history cross-checking, DistroWatch's Batocera page is a useful named source that tracks the dates independently of the project's own site.

Rolling-ish, and why the update URL matters

Relative to older fixed-release retro distributions, Batocera behaves more like a rolling project: point releases land on a live mirror, and the system can pull them in place rather than forcing a full re-flash. That is a philosophy difference worth understanding, because it means the download page is only your entry point — after that, the update URL structure (which we get to in the CLI section) becomes the thing you actually operate. It also means version discipline matters more than with a distro you install once and forget. If you care about that kind of firmware-versioning rigor, the way we tracked it across twelve firmware builds on the Analogue 3D is the same mindset you want here: know exactly which build you are on, and why.

Prerequisites: Hardware and Software

Skip this section and you will hit the storage wall at step 6 or the wrong-architecture wall at step 8. Neither is fun. Read it now; it takes two minutes.

Storage: the 16 GB floor, 32 GB for real

The official install wiki is blunt about this: 16 GB of storage is the minimum, and 32 GB is recommended for full functionality. The catch that nobody mentions until it bites: Batocera's automatic updates cannot run on a 16 GB card, because the in-place upgrade needs room to stage a second system partition. On 16 GB you can boot and play, but you cannot auto-update — you would be stuck re-flashing by hand every release. Buy 32 GB or more. It costs a couple of dollars extra and removes an entire category of future pain. Below is the requirements table in full.

RAM is not the bottleneck

Note what the table does not claim: a RAM minimum. The Batocera wiki publishes no RAM floor, and the distribution runs on a Raspberry Pi Zero 2 W with 512 MB. So when a content farm tells you that you "need 4 GB of RAM" to download Batocera, understand that it is inventing a spec to sound authoritative. Your constraints, in order, are storage capacity, storage speed, and the GPU/CPU of the target device. Memory is the last thing you should worry about. If your device can run any modern retro front end, it can run Batocera.

The software: Imager, USBImager, Etcher

On the host machine — the Windows, macOS, or Linux computer you will flash from — you need exactly one image-writing tool. The wiki's primary recommendations are Raspberry Pi Imager and USBImager. The widely known cross-platform alternative is Balena Etcher, from etcher.balena.io, which the wiki lists in its troubleshooting notes and which a great many 2026 tutorials point to by name. All three accept the compressed .img.gz directly and decompress it on the fly, so you do not gunzip the file first. You also need a card reader and, for a Raspberry Pi target, a power supply that actually meets spec — an underfed Pi is the most common "it won't boot" report there is, and it has nothing to do with the download.

Picking the Right Architecture

This is where most first attempts die. Batocera does not ship one universal image; it ships a per-architecture image, and downloading the wrong one gets you a black screen with no error message. Match the file to your hardware exactly.

x86_64 versus x86_64-v3

For PCs, there are three x86 targets on the download page. Plain x86_64 is the safe generic choice for any standard PC, laptop, NUC, or Intel-based Mac. x86-64-v3 is the newer micro-architecture build — it assumes AVX2 and the rest of the v3 feature level, which is why it is the recommended image for Zen 3-and-later chips, the Steam Deck, and modern x86 handheld PCs. If your CPU is recent, v3 gives you the better-optimized graphics stack (this is the image that got the Wayland/LabWC overhaul in Glasswing). If you are unsure or your hardware is older, take plain x86_64 and move on. There is also a legacy 32-bit x86 image for machines twenty-plus years old, which almost nobody reading this needs.

Raspberry Pi board codes

The Pi images are named by SoC, not by marketing name, so you must translate. The mapping the download page uses:

Note that Batocera and Recalbox both ship Pi 5 images, which is one reason many builders have migrated to them; by contrast, the once-dominant RetroPie image has been frozen for years, as we covered in RetroPie's stuck-at-v4.8 situation. If you already have a running Batocera install and want to confirm which build it expects, the board string is one command away.

$ cat /boot/boot/batocera.board
bcm2712

Handhelds: Retroid, Anbernic, Odin, Rockchip

The download page also carries dedicated handheld images. You will find targets for the Anbernic RG line (the h700 SoC covers the RG35XX family), the Ayn Odin 2 series, the Retroid Pocket range (5, 6, Mini, Flip 2), and a spread of Rockchip and Amlogic single-board computers — rk3588 for the high-end Rockchip devices, sm8550 for Snapdragon-class handhelds, jh7110 for StarFive boards. The rule is identical to the PC case: download the image named for your specific device, not a generic one. A Retroid Pocket owner comparing SD865 to SD8-Gen-2 silicon in our Retroid Pocket 6 versus 5 breakdown still has to grab the Retroid-specific Batocera build; there is no substitute image that "just works" across chips.

The 12-Step Walkthrough

Here is the whole procedure, download to first game, as twelve numbered steps. Each one carries its rationale, because a step you understand is a step you can debug. The clusters after the list expand on the parts that trip people up.

1. Confirm the current stable version at the source. Open batocera.org/download and read the version label — it should say 43.1. Rationale: version numbers are the farms' favorite lie; anchoring on the official page immunizes you against fakes.
2. Identify your exact architecture. Match your device to the arch list from the previous section. Rationale: the wrong image is the single most common cause of a dead first boot, and it fails silently.
3. Download the matching .img.gz (about 3 GB). One file per architecture; take the one for your hardware. Rationale: that single archive contains all 200-plus systems — there is nothing else to fetch.
4. Verify the archive integrity. Run a gzip test or check the size before you write. Rationale: a truncated download flashes a corrupt image that boots to nothing, and you will wrongly blame the card.
5. Install a flashing tool. Raspberry Pi Imager or USBImager (wiki primary), or Balena Etcher (the popular alternative). Rationale: these write a raw image byte-for-byte; a normal file copy will not produce a bootable card.
6. Insert the target media — 32 GB or larger. Use a good card or a USB SSD. Rationale: 16 GB is the bare floor and kills auto-updates; 32 GB is the real minimum for a system you will keep.
7. Flash the image, selecting the .img.gz directly. Do not decompress it first. Rationale: all three tools unzip on the fly; manually gunzipping just wastes 8 GB of disk and a step.
8. Move the media to the device and boot. Card into the Pi or handheld; USB into the PC's boot order. Rationale: first boot auto-resizes the userdata partition to fill the card, which only happens on the target hardware.
9. Reach the EmulationStation menu and configure your controller. Follow the on-screen pad-mapping prompt. Rationale: arriving at the menu confirms the arch and the flash are both correct; input mapping is what makes it usable.
10. (Optional) Install to internal disk. SYSTEM SETTINGS → INSTALL BATOCERA ON A NEW DISK. Rationale: SD cards are slow and eventually die; an internal SSD or eMMC is faster and far more durable.
11. Add ROMs and BIOS over the network share. Copy your own game dumps into the share, no re-flash required. Rationale: the install ships empty by design and by law; you supply content you own.
12. Run batocera-check-updates and set your update channel. Confirm you are on 43.1 and pick stable. Rationale: it locks in a known-good version and a sane in-place upgrade path going forward.

Steps 1-4: get the right file, prove it is intact

The front half is all about not fooling yourself. Version from the official page, architecture matched to silicon, one archive, and — critically — a verification pass before you commit it to a card. The reason step 4 exists as its own line is that gzip corruption is invisible until boot: the file looks complete, the flash "succeeds," and then the device hangs on a black screen while you disassemble your setup looking for a hardware fault that is not there. Thirty seconds of verification up front saves that entire detour.

Steps 5-8: flash without gunzipping first

The middle four are the mechanical part, and the only subtlety is step 7: feed the flashing tool the compressed .img.gz as-is. Raspberry Pi Imager, USBImager, and Etcher all decompress transparently. People who manually extract the image first are not wrong exactly, just doing unnecessary work and burning disk space. Step 8's auto-resize is the quiet hero — you do not have to expand partitions by hand the way you would on a hand-rolled Linux install; Batocera grows userdata to fill whatever you gave it, the first time it boots on the real device.

Steps 9-12: expand, populate, pin

The back half turns a booted image into a system you will actually keep. Controller mapping (step 9) is table stakes. The optional internal install (step 10) is the upgrade that most people wish they had done sooner. Loading games (step 11) is the part that takes real time, because organizing a library is its own project — the kind of dedup-and-curate work we documented turning 28,000 raw files into a usable set on the Miyoo Mini Plus. And pinning your update channel (step 12) is the discipline that keeps you from drifting onto a broken build by accident.

Verifying the Download

This section is short because the action is short, but do not skip it. Verification is the cheapest insurance in the entire process.

Why a bad download is silent

A partial or corrupted image does not announce itself. Your browser reports the download "complete," the flashing tool reports the write "successful," and the device then does nothing — black screen, no logo, no error. Every symptom points you at hardware: bad card, bad reader, bad power. The actual culprit is a handful of missing bytes at the tail of a 3 GB archive. Because the failure mode is so misleading, verifying before you flash is worth the thirty seconds it takes.

Test the gzip integrity

On Linux or macOS, gzip can test its own archive without extracting it. A silent success (or an explicit "OK") means the compressed stream is intact end to end; any error means re-download. On Windows, 7-Zip's "Test archive" does the same job from the right-click menu.

$ ls -lh batocera-x86_64-43-20260530.img.gz
-rw-r--r-- 1 you you 3.0G May 30 12:00 batocera-x86_64-43-20260530.img.gz

$ gunzip -t batocera-x86_64-43-20260530.img.gz && echo "archive OK"
archive OK

Expected sizes and checksums

Two sanity checks beyond the gzip test. First, size: the compressed x86_64 image is on the order of 3 GB; if your file is a few hundred megabytes, the download died early and you have an HTML error page with an .img.gz extension. Second, when the project publishes a checksum alongside a release, compare it — a matching SHA is definitive proof of a byte-perfect download in a way that a size check is not. If everything lines up, the image will expand to roughly 8 GB when written, and grow again on first boot. Only now should you flash.

Flashing: Imager First, Etcher Second

Writing the image is the least interesting step and the easiest to get catastrophically wrong, because the one mistake available to you — selecting the wrong target disk — wipes whatever was on it. Slow down for exactly one screen.

Raspberry Pi Imager and USBImager (the wiki's picks)

The Batocera install wiki puts Raspberry Pi Imager and USBImager first, and they are the ones to reach for. In Raspberry Pi Imager you choose "Use custom" for the OS, point it at the .img.gz you verified, select your card as the storage target, and write. USBImager is even more spartan: pick image, pick device, click write. Neither requires you to decompress the archive first. The one screen that matters is the target selector — read the device name and capacity and make sure it is the card, not your system drive or an external backup. This is the step where haste turns into data loss.

Balena Etcher (the popular cross-platform alternative)

If you already have Balena Etcher installed, or you want a single tool that behaves identically on Windows, macOS, and Linux, it does the job cleanly: "Flash from file," pick the .img.gz, "Select target," pick your card, "Flash." Get it from etcher.balena.io and nowhere else — Etcher is exactly the kind of popular utility that farms wrap in adware installers. Etcher's advantage is that it hides your system drives by default, which makes the fatal wrong-target mistake harder. Its disadvantage is nothing that matters for this task. Wiki-primary or not, any of the three produces an identical bootable card.

Expected flash output and the write-verify pass

A normal flash runs two passes: a write pass that streams the decompressed image onto the media, and a verify pass that reads it back to confirm the bytes landed. Do not cancel during verify — that pass is what catches a flaky card before it wastes your time on the device. When the tool finishes, it typically ejects the media on its own. Expect the whole write-plus-verify to take a few minutes on a decent USB 3 reader, longer on a slow SD card. If verify fails, the card is suspect: try another one before you blame the download you already verified.

First Boot and Expanding Storage

The card is written. Now it becomes a system. First boot does more than start a menu; it finalizes the install.

The boot sequence and the auto-resize

Put the card in the device (or set your PC to boot the USB) and power on. On first boot, Batocera automatically resizes the userdata partition to consume the free space on the media — this is why you flash to the real target and let it boot there, rather than expecting the flashing tool to have done it. After the resize, the system lands in EmulationStation and prompts you to map a controller. Follow the prompt; the on-screen guide walks each button. Reaching a mapped, navigable menu is your proof that both the architecture and the flash were correct. If instead you get a black screen or, on a Pi, a rainbow square, jump to the troubleshooting table — those are known, named failure modes with known fixes.

Install to internal disk (optional but recommended)

Running from the SD card forever is fine for a Pi you treat as disposable, but on any device with internal storage you should move in. Navigate to SYSTEM SETTINGS → INSTALL BATOCERA ON A NEW DISK, pick the internal SSD or eMMC as the target, and let it copy over. The payoff is speed and longevity: internal flash has far better random-read performance than a typical SD card, which shows up directly as faster menus and shorter load times, and it does not wear out the way a cheap card does under constant writes. Do this before you spend hours loading a library you would rather not migrate later.

The /userdata layout

Everything you will ever touch lives under a single directory, /userdata, and it survives updates. Learn these four folders and you understand the whole system.

/userdata
  roms/    # your games, one folder per system (short names)
  bios/    # BIOS / firmware files the cores expect
  saves/   # save files and save states
  system/  # batocera.conf, logs, and configuration

The configuration file is /userdata/system/batocera.conf, and you can reach the whole tree over SSH — the default login is user root, password linux, which you should change if the box lives on a shared network. Knowing this layout is what lets you back up a build (copy /userdata), migrate it, or fix it by hand when the menu will not cooperate.

Adding ROMs and BIOS

A fresh Batocera install has zero games. That is not an oversight; it is the entire legal posture of the project. Batocera distributes an emulator and an operating system, not copyrighted content, and it stays clean by shipping empty and making you the source of the ROMs.

The network share is the front door

You do not pull the card back out to add games. Batocera exposes its folders as a network share, so you copy files from any computer on the same network. The paths:

# Windows / macOS (SMB):
\\BATOCERA\share

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

# By IP (any OS, if name resolution is flaky):
\\192.168.1.50\share

Open the share, and you are looking straight at the roms and bios folders you saw in the /userdata tree. Drag files in over the network; EmulationStation picks them up after a refresh or reboot. No re-flash, no card-shuffling.

roms/<shortname> and the _info.txt contract

ROMs go into share/roms/<shortname>, where the short name is the system's folder key — snes for Super Nintendo, genesis for Mega Drive, psx for PlayStation, and so on. Put a file in the wrong folder and it simply will not appear. Every system folder ships with an _info.txt that lists the emulators available for that system and the file extensions it accepts; when a game refuses to show up, that file is the first thing to read.

share/roms/snes/      ← Super Nintendo    (read _info.txt for accepted extensions)
share/roms/genesis/   ← Sega Genesis / Mega Drive
share/roms/psx/       ← Sony PlayStation  (needs BIOS, see below)
share/bios/           ← BIOS / firmware files go here, not in roms/

Where those ROMs come from is your responsibility and, in most jurisdictions, hinges on owning the original media and dumping it yourself. If you want the clean, defensible path, dumping your own cartridges is a solved problem — we walked the full process in dumping a cart with a Retrode in twelve steps. The Machine's position is simple: back up media you own.

BIOS files and the libretro list

Some systems — PlayStation, Sega CD, various handhelds — need a BIOS the emulator cannot legally include. Those go in share/bios/, and the cores are picky about exact filenames and hashes. The authoritative reference for which file each core wants, down to the MD5, is the libretro BIOS documentation. Match the filename and hash exactly; a renamed or slightly-wrong BIOS is the second-most-common "why won't this run" after wrong-folder ROMs. Note also that Batocera 43 changed some emulator requirements — the DraStic DS emulator was removed in favor of melonDS (and DS saves do not transfer between them), and 3DS ROMs must now be decrypted — so if you are migrating a library from an older version, check the changelog before assuming everything carries over.

Updating and Downgrading From the CLI

Because Batocera is rolling-ish, the command line gives you precise control over which build you run. This is where you graduate from "downloaded it once" to "operate it deliberately." All of this is documented on the manual upgrade wiki.

batocera-check-updates: read before you leap

Before upgrading anything, ask the system where it stands. batocera-check-updates reports your installed version, the version available on the web, the update URL it would use, your branch, your architecture, and a status line. It is the single command that answers "am I current?" without guessing.

$ batocera-check-updates
Local version:  43
Web version:    43.1
Update URL:     https://mirrors.o2switch.fr/batocera/x86_64/stable/last
Branch:         stable
Architecture:   x86_64
Status:         A newer version is available

batocera-upgrade [URL]: the manual path

For in-place upgrades and downgrades, the wiki-documented command since Batocera 5.23 is batocera-upgrade [URL]. Point it at the mirror path for your architecture. To take the latest stable for x86_64, use the stable/last path; to pin or roll back to a specific major, substitute that major's number in the path; and for a fully manual, offline-capable upgrade on version 39 and later, drop the release's boot.tar.xz into /userdata/system/upgrade and run the manual form.

# Upgrade to the latest stable for your architecture:
batocera-upgrade https://mirrors.o2switch.fr/batocera/x86_64/stable/last

# Pin / downgrade to a specific major (e.g. 42 "Papilio"):
batocera-upgrade https://mirrors.o2switch.fr/batocera/x86_64/stable/42/

# Fully manual (v39+): place boot.tar.xz in /userdata/system/upgrade, then:
batocera-upgrade manual

Every one of these preserves /userdata, so your ROMs, saves, and config survive the version change. Older official builds remain available under the project's mirror infrastructure, including architecture-specific stable archives, which is precisely what makes a clean downgrade possible when a new release breaks something you rely on.

UI branch switching and pinning a major

If you would rather not touch a terminal, the same channel control lives in the interface. Per the current and previous releases wiki, you switch channels via MAIN MENU → UPDATES & DOWNLOADS → UPDATE TYPE, choosing stable, beta, or another branch. Stable is what you want for a system you actually use; beta is for people who enjoy filing bug reports. The practical discipline is this: run batocera-check-updates before any big update session, know exactly which build you are moving to, and keep the mirror path for your current major written down so that rolling back is a one-line command, not a research project.

Five Pitfalls That Eat Your Afternoon

These are the failure modes that turn a 30-minute job into a lost evening. Each has a specific, known fix. Read them now so you recognize them when they happen.

The 16 GB trap and the dead auto-updater

Pitfall 1 — the 16 GB card. You flash to a 16 GB card because it was in the drawer, everything works, and then months later auto-update refuses to run. This is not a bug; auto-updates need more than 16 GB to stage the new system partition. Fix: use a 32 GB or larger card from the start, or accept that on 16 GB you will re-flash by hand each release. There is no software workaround for physics.

Wrong architecture, wrong folder name

Pitfall 2 — wrong architecture. You grabbed x86_64 for a Pi, or a generic image for a specific handheld, and the device boots to black. Fix: re-download the image named for your exact hardware; on a working reference install, cat /boot/boot/batocera.board tells you the correct board string. Pitfall 3 — ROMs in the wrong folder. Games do not appear because they are in the wrong system folder or an unsupported extension. Fix: place them in share/roms/<shortname> and read that folder's _info.txt for accepted formats.

The v43 breaking changes and the fake mirrors

Pitfall 4 — assuming everything carries over from 42. Batocera 43 removed DraStic (DS now runs on melonDS, and saves do not transfer), requires decrypted 3DS ROMs, and renamed Azahar Plus to Azahar. Fix: read the changelog before migrating a library, and re-dump or convert what changed. Pitfall 5 — the fake download mirror. A search for "batocera download" surfaces content farms offering a "faster" or "premium" mirror, sometimes with a version number that does not exist. Fix: download only from batocera.org/download; the image is free, and anyone charging or gating it is selling you a problem. A sixth, honorable-mention pitfall: skipping the archive verification in the download section, which converts a truncated file into a mystery hardware fault. Do the gunzip -t.

Troubleshooting and a Working Config

The reference material: a symptom-to-fix table, the advanced moves worth knowing, and a complete, commented configuration file you can adapt.

Troubleshooting table

Match your symptom to the likely cause and the fix. Several of these fixes are simply "update to 43.1," because 43.0 shipped with exactly these bugs and the point release resolved them — which is the whole reason this guide targets 43.1 specifically.

Advanced tips

Once the basics work, these are the moves that separate a casual setup from a maintained one. Pin a major. Because Batocera rolls, keep the mirror path for your current major (for example stable/42/) written down; if a new release breaks a core you depend on, batocera-upgrade back to it in one line, /userdata intact. Operate over SSH. Log in as root/linux to edit batocera.conf, tail logs, or bulk-move ROMs faster than the network share allows. Keep an offline copy of your exact image. The farms rot and even official filenames change; a saved, verified .img.gz for your architecture and date is your guaranteed rollback, and the project's mirror keeps older stable archives besides. Learn the config override hierarchy. Batocera resolves settings game-first, then folder, then system, then global — set a shader globally and override it per system when one console needs different treatment. Move userdata to a second drive. On a PC, keep a small boot device and point /userdata at a large SSD, so re-flashing the OS never touches your library. And treat versioning with the same rigor you would firmware on dedicated hardware — the discipline that mattered across the Analogue 3D's firmware builds is exactly the habit that keeps a rolling distro from drifting onto a broken build behind your back.

The complete working batocera.conf

Finally, a complete, commented /userdata/system/batocera.conf you can adapt. These are real key namespaces; edit the values for your setup, and consult the install wiki for the full syntax reference before adding exotic keys. Edit it over SSH or by mounting the share, then reboot.

## /userdata/system/batocera.conf  --  representative working config
## Full syntax reference: wiki.batocera.org (batocera_conf_syntax)

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

## --- Network ---
wifi.enabled=0
## To use Wi-Fi, set enabled=1 and fill both fields below, then reboot:
## wifi.ssid=YourNetwork
## wifi.key=YourPassword

## --- Updates (channel + auto-update; needs >16 GB media) ---
updates.enabled=1
updates.type=stable

## --- Global emulator defaults (override per-system below) ---
global.retroachievements=0
global.rewind=1
global.autosave=0
global.smooth=1
global.shaderset=none
global.bezel=none
global.ratio=auto

## --- Per-system override example: SNES gets a CRT shader ---
snes.emulator=libretro
snes.core=snes9x
snes.shaderset=scanlines

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

## --- Network share cheat sheet (not a config key, just a reminder) ---
## Windows/macOS:  \\BATOCERA\share
## Linux:          smb://BATOCERA.local/share
## ROMs  -> share/roms/<shortname>/    BIOS -> share/bios/

That is the whole arc: one free 3 GB image from the one legitimate source, matched to your architecture, verified, flashed, expanded, populated with games you own, and pinned to a known-good 43.1. The download was step one of twelve — and now you know why each of the other eleven exists.