Batocera Download 2026: 43.1 in 12 Steps, 30 Min

There is a specific flavour of disappointment reserved for the person who spends forty minutes writing a Batocera image to a USB stick, boots it, and watches the screen stay black. Nine times out of ten the stick is fine and the flashing tool did its job perfectly. They simply downloaded the wrong file. Batocera is not one download; it is a family of architecture-specific images that happen to share a name, and picking the wrong member of that family is the single most reliable way to waste an evening.

This guide exists to stop that before it happens. It walks you from a cold browser tab to a booted, game-ready system in twelve numbered steps and roughly thirty minutes of active work, most of which is spent watching a progress bar. Every step has a reason attached, because a tutorial that tells you to click a button without telling you why is just a liability with screenshots. We are using Batocera 43.1, the current stable release as of July 2026, and we are going to be honest about the parts the marketing-flavoured guides skip: the BIOS files that will never be in the box, the 16 GB storage cliff, and the one menu choice that can irreversibly corrupt the stick you booted from.

A housekeeping note before we start. Several 2026 walkthroughs floating around content farms get the version history wrong, and some cite domains I would not trust to tell me the date. Where this guide points you at documentation, it points at the project's own: batocera.org/download, the Batocera install wiki, and the source repository on GitHub. If a guide tells you to download Batocera from anywhere other than batocera.org, close the tab.

What Batocera Actually Is

Before you download anything, it helps to know what you are downloading, because Batocera is routinely mis-sold as 'an emulator' by people who have never used it. It is not an emulator. It is an entire operating system whose only job is to run emulators, and that distinction changes how you install it, how you update it, and what can go wrong.

An operating system, not an app you launch

RetroArch is an app. EmuDeck is a script that configures apps on an existing OS. Batocera is a complete, self-contained Linux distribution: it boots the machine, brings up its own kernel (6.15.11 in the 43.x line), its own display stack, and a front-end called EmulationStation, and then hands control to a curated set of emulator cores across 200-plus systems. You do not install Batocera into Windows. You write it to a drive and boot the whole computer from it. That is why the download is an image of a bootable disk rather than a setup executable, and why the flashing step is non-negotiable.

The practical upshot: Batocera turns a cheap mini PC, an old laptop, a Raspberry Pi, or a Steam Deck into a dedicated console with no Windows tax and no background updates fighting you for the GPU. If you have ever wrestled with the sprawl of the RetroArch core catalogue, Batocera's appeal is that it has already made those choices for you and wired them into a controller-driven menu.

Free, open-source, and it ships nothing

Batocera is a 100% free, open-source project, licensed CC-BY-NC-SA, copyright 2016-2026, with the full source on GitHub. There is no paid tier, no 'pro' unlock, and no telemetry shakedown. What there also is not, anywhere in the image, is a single game or a single BIOS file. This is deliberate and legal, not an oversight. Batocera ships the machinery; you supply the media. Anyone selling you an SD card 'pre-loaded with 40,000 games and Batocera' is selling you someone else's copyright infringement with a markup, and the project explicitly disclaims them.

The clean way to source what Batocera won't give you is to dump the cartridges and discs you already own. That is a legitimate rabbit hole in its own right, and if you want the hardware-and-workflow version of it, our guide to dumping SNES and Genesis carts covers the honest path from plastic to .sfc.

The release you want: 43.1, not 43.0

Here is where the content farms trip. Batocera 43, codenamed 'Glasswing', was published on 8 May 2026. Its headline changes were graphics-oriented: a new x86_64-v3 image tuned for modern AMD and Intel CPUs, a move to the Wayland display protocol with the LabWC compositor, and experimental handling for Nvidia GPUs. Three weeks later, on 30 May 2026, the project shipped 43.1 as a stability patch. Some 2026 guides mash those two dates together and call 43.1 itself 'Glasswing', or claim the whole 43 line dropped on 30 May. It didn't. 43 is the feature release; 43.1 is the fix-up.

And you want the fix-up. Batocera 43.1 corrected a genuinely annoying set of 43.0 regressions: EmulationStation dropping systems and collections at random, LR-Dolphin's options being broken, Steam and Flatpak breakage, LR-MAME light-gun input failing, and, my favourite, Microsoft controllers being detected as keyboards. Downloading 43.0 in July 2026 means volunteering for bugs that were already fixed. Take 43.1.

Prerequisites: Hardware, Versions, Tools

The failure modes in this project cluster at the beginning: wrong hardware assumptions, wrong image, wrong tool. Clear the prerequisites and the rest is a progress bar.

Hardware floor, and what actually matters

Batocera's stated minimums are modest: 1 GB of RAM to boot, 2 GB recommended, and 16 GB of storage minimum with 32 GB recommended. Pay attention to that storage number, because it is not merely a suggestion. Below 16 GB, Batocera disables its own in-place updater, and you will discover this the first time you try to upgrade and nothing happens. On first boot, the system auto-expands its userdata partition to fill whatever drive you gave it, so a 32 GB stick becomes ~32 GB of usable space without you doing anything.

RAM and CPU only start to matter as you climb the console ladder. 8-bit and 16-bit systems will run on a potato. The moment you reach GameCube, PS2, Wii, or Switch, you are into serious x86 territory, and the quality of your GPU and the wattage of your cooling determine whether you get 60 fps or a slideshow. If you are building on a desktop and plan to push the demanding cores, it is worth reading up on how far you can safely lean on the silicon; our GPU overclocking walkthrough is the sober version of that conversation. For the FPGA-accuracy crowd who consider software emulation a compromise, that is a different machine entirely, and the MiSTer Multisystem 2 is where that argument lives.

The image, and the tool that writes it

You need two things: the correct Batocera image and a program that writes raw disk images to removable media. The image is a compressed .img.gz file, roughly 3 GB as downloaded, which decompresses to about 8 GB when written. Do not unzip it yourself; the flashing tools handle the decompression on the fly.

For the writing tool, the official install wiki recommends Raspberry Pi Imager or USBImager, and its own example walkthrough uses Raspberry Pi Imager. Both are free, cross-platform, and boringly reliable, which is exactly what you want from a tool whose failure mode is 'unbootable drive'. A third common choice is balenaEtcher, which many 2026 consumer guides reach for; it works fine, though it is a heavier Electron app that phones home more than the alternatives, so I default to Raspberry Pi Imager and reach for Etcher only out of habit. Any of the three will write a valid stick. What you must not use is a file copy: dragging the .img.gz onto a USB drive in your file manager produces a drive with a file on it, not a bootable image.

The two files Batocera will never give you

Games and BIOS files are on you, and the BIOS half is where most first-time installs stall. A BIOS is the small firmware blob some consoles need before an emulator can pretend to be them; the PlayStation, Sega CD, and PS2 cores, among others, refuse to run without the correct one. Batocera cannot legally distribute these, so you must place them yourself, and they are hash-checked: a file with the right name but the wrong bytes is treated as missing. The libretro project maintains the canonical reference of which system needs which file and what its checksum should be, at the libretro BIOS documentation. Have that tab open before you start copying, and you will skip an entire category of 'why won't this game load' confusion.

Pick the Right Image (Steps 1-3)

This is the section that determines whether the next twenty-five minutes end in a menu or a black screen. Get the architecture right and everything downstream just works.

Step 1 - Open the real download page

Go to batocera.org/download. Not a mirror you found on a forum, not a Google Drive link in a YouTube description, not a torrent. The official page is where the current stable image lives, where the architecture picker lives, and where you can be certain the bytes have not been tampered with. Rationale: a Batocera image runs as your entire operating system with root access to your hardware. Sourcing it from anywhere but the project itself is the security equivalent of eating something you found on the pavement. The page offers 43.1 by default; that is the one you want.

Step 2 - Identify your architecture

The download page asks you to choose an image that matches your hardware architecture, and this is the choice everything hinges on. The wiki is blunt about it: the image must match the platform, x86_64 is the standard choice for the overwhelming majority of PCs, and every other device uses its own hardware-specific build. A Raspberry Pi image will never boot a PC, and vice versa. There is no universal image.

Use this map to translate your device into the architecture string in the filename:

If you are unsure, or you are re-imaging a machine that already runs Batocera, you can ask the machine directly. On a running install the board name is one file away; deciding from scratch on a target PC, your operating system already knows its own architecture:

## On an existing Batocera install (SSH or F1 terminal):
cat /boot/boot/batocera.board
## -> bcm2712        (that is a Raspberry Pi 5)

## Deciding from scratch, on the target PC:
uname -m                          ## Linux/macOS: x86_64  -> use the x86_64 image
lscpu | grep -i 'model name'      ## AMD Zen 3 or newer? x86_64-v3 is faster

Rationale: the x86_64-v3 image is compiled for the newer instruction sets in Zen 3-and-later and comparable Intel chips, so on a Steam Deck or a modern desktop it is measurably quicker than the plain x86_64 build. On anything older it simply will not boot, which is the entire point of choosing carefully. When in doubt on a PC, plain x86_64 is the safe default that runs everywhere.

Step 3 - Read the filename before you trust it

Batocera names its images to a fixed convention: architecture, then version, then build date. Once you know the pattern, the filename becomes a receipt you can verify at a glance, which is exactly what you want before committing it to a drive.

## What a real 2026 image name looks like:
batocera-x86_64-43.1-20260530.img.gz
##        ^arch   ^ver  ^build-date

## Sanity-check the download before flashing:
ls -lh   batocera-x86_64-43.1-20260530.img.gz   ## ~3 GB compressed
gunzip -l batocera-x86_64-43.1-20260530.img.gz   ## uncompressed ~8 GB

Rationale: if the architecture token in the filename does not match the table above, you have the wrong image and no amount of flashing will fix it. The date token (20260530) is your confirmation that you pulled the 30 May 2026 stable build rather than an older snapshot. A ~3 GB download that expands toward ~8 GB is the expected shape; a file that is only a few hundred megabytes is a truncated download, and you should fetch it again rather than flash a corrupt image and spend an hour blaming your USB stick.

Flash the Image (Steps 4-6)

With the correct .img.gz on your disk, the writing itself is the easy part. The care is in choosing the right target drive and confirming the write actually landed.

Step 4 - Choose a flashing tool and target

Open Raspberry Pi Imager (or USBImager, or balenaEtcher). In Raspberry Pi Imager, choose 'Use custom' under the OS list and point it at your .img.gz; the other tools have an equivalent 'select image' button. Then select the destination. Batocera's install guide is generous about what that destination can be: a USB drive, an SD card, a hard drive, or an SSD, including an external SSD hung off a SATA-to-USB or M.2-to-USB cable. Rationale: the destination is where Batocera will live and where your saves will accumulate, so favour something fast and durable. An external SSD over USB 3 boots and loads dramatically faster than a cheap flash drive and will not wear out in a year of save-writing. A USB stick is perfectly fine for trying Batocera; an SSD is what you want if you intend to keep it.

Read the drive letter twice. The flashing tool overwrites the target completely, and it does not care whether that target is a cheap USB stick or the external drive holding your only copy of something irreplaceable. Confirm the size and label match the drive you intend to erase before you click write.

Step 5 - Write the .img.gz without decompressing it

Hand the tool the compressed .img.gz directly and let it decompress-and-write in one pass. Do not gunzip it to a raw .img first; every recommended tool reads the gzip stream natively, and the extra step only wastes disk space and invites you to accidentally flash the wrong file. Start the write. This is the ten-to-twenty-minute progress bar, its length set almost entirely by the write speed of your target: an SSD finishes in a couple of minutes, a budget SD card can take twenty. Rationale: the tools verify as they write, which is the whole reason to use them over a manual dd. Let it finish; interrupting a half-written image produces a drive that boots partway and then dies in the ugliest, most confusing way possible.

Step 6 - Verify the write and eject cleanly

When the tool reports success, do not just yank the drive. Let it finish verifying, then eject it properly so the OS flushes its write cache. If you want to confirm the geometry before you unplug, a quick look at the partition table tells you the write landed:

$ lsblk -o NAME,SIZE,FSTYPE,LABEL
NAME   SIZE FSTYPE LABEL
sdb   28.9G
sdb1   2.5G vfat   BATOCERA     ## boot + system partition
sdb2   1.0M                     ## userdata placeholder, expands on 1st boot

Rationale: a freshly flashed Batocera drive shows a small labelled BATOCERA boot partition and a tiny second partition that looks alarmingly small. That is correct. The userdata partition is a placeholder that Batocera grows to fill the drive the first time it boots, which is exactly why you should not pre-format or resize anything by hand. Pull a properly ejected stick; it is now a bootable Batocera installer and, for many people, the finished product.

Boot and Configure (Steps 7-9)

The drive is ready. Now you convince the target machine to boot from it, which on modern hardware means having a brief argument with the firmware.

Step 7 - Boot from the stick

Plug the drive into the target machine and power it on while tapping the boot-menu key. That key is a coin flip by vendor: F12, F11, F10, Esc, or F8 on most PCs, sometimes F9. Choose the USB drive from the list. Many machines distinguish a 'UEFI: [drive]' entry from a plain legacy one; on a modern PC pick the UEFI entry. Rationale: booting from the menu once, rather than permanently reordering the boot priority, means you are not committing to anything yet. Batocera will run live off the stick, you can decide whether you like it, and your existing OS is untouched on the internal drive. If Batocera loads to its animated splash and then EmulationStation, the image and the architecture were both correct and the hard part is over.

Step 8 - Disable Secure Boot if it refuses

If the machine simply will not boot the stick, skips past it, or throws a security error, the culprit is almost always Secure Boot. Enter the firmware setup (Del, F2, or F10 at power-on, again vendor-dependent), find Secure Boot under a Security or Boot tab, and set it to Disabled. While you are there, confirm USB is enabled in the boot order and, on older machines, that the drive is not being blocked by a Legacy/UEFI mismatch. Save and exit. Rationale: Secure Boot only trusts bootloaders signed by keys it already holds, and Batocera's is not among them by default. This is not Batocera being sketchy; it is the same reason a fresh Linux install trips the same wire. Disabling it is safe and reversible, and it is the fix that a great many 'Batocera won't boot' threads eventually arrive at after an hour of thrashing.

Step 9 - Let the first boot expand userdata

The very first boot does more than the rest: Batocera detects your hardware, generates its default configuration, and expands that placeholder userdata partition to fill the entire drive. This takes a minute or two longer than subsequent boots and may reboot itself once. Leave it alone until you land on the EmulationStation main menu. Rationale: that expansion is what turns your 32 GB stick into 32 GB of usable game storage; interrupting it by pulling power mid-expand is a good way to corrupt the fresh install and start over. Once you are at the menu, plug in a controller (most are recognised automatically) and follow the on-screen prompt to map its buttons. You now have a working, if empty, retro console running entirely from the drive you flashed.

Install to Internal Disk (Steps 10-12)

Running live from USB is a legitimate permanent setup, not just a trial. But if the machine is going to be a dedicated Batocera box, installing to an internal SSD is faster and frees the USB port. This is optional, and it is also the step with the one truly destructive footgun in the whole process.

Step 10 - Decide: live USB or internal install

Ask yourself whether this machine has another job. If it dual-boots Windows, or the internal drive holds anything you care about, stay on the USB and stop here; a good USB 3 SSD is indistinguishable from an internal one in daily use. If the machine is a bare mini PC destined to be nothing but a console, installing to its internal drive is worth it: internal SATA or NVMe is faster than USB, boot times shrink, and you reclaim the port. Rationale: the internal install is a convenience, not a requirement, and framing it that way keeps you from wiping a drive you meant to keep. There is no performance penalty to living on external storage forever if that is what fits your situation.

Step 11 - INSTALL BATOCERA ON A NEW DISK

From the booted USB system, open the front-end menu and navigate to MAIN MENU -> SYSTEM SETTINGS -> INSTALL BATOCERA ON A NEW DISK. This copies the running system onto internal storage (or any other target drive) and sets it up to boot on its own. Choose your target disk, pick the file system if prompted (the default is fine), and let it run. Rationale: this is the supported, documented path, described step for step in the official install wiki. It does the partitioning, copying, and bootloader work for you, which is far less error-prone than any manual clone. When it finishes, shut down, remove the USB stick, and boot from the internal drive.

Step 12 - Never pick the disk you booted from

This is the one that bites people, so it gets its own step. When the installer asks which disk to install to, it will list the USB stick you are currently running from among the options. Do not select it. The Batocera wiki warns in plain language that choosing the drive you are booted from can corrupt your USB stick, and that the action is irreversible. Rationale: you are asking the system to overwrite the disk it is actively reading its own code from, which ends exactly as badly as it sounds. Identify the target by its size and label, confirm it is the internal drive and not the installer, and only then proceed. If you are ever unsure which entry is which, cancel and check the disk sizes first; a wrong guess here does not get an undo.

Adding Games and BIOS Files

Batocera is installed and running and completely empty, because it ships nothing. Filling it is its own small discipline, and getting the folder layout and BIOS hashes right the first time saves a great deal of 'it says the game is there but won't launch' bewilderment.

The network share is the front door

The cleanest way to move files onto Batocera is over the network. Batocera exposes its storage as a share the moment it is on your LAN, so you copy from your everyday computer with no card-reader shuffling. Connect to it like any file server:

## From Windows Explorer or macOS Finder (Go -> Connect to Server):
\\BATOCERA\share
\\192.168.1.50\share          ## use the IP if the name will not resolve

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

## Drop files into these folders:
share/roms/<system>/           ## games, e.g. share/roms/snes/
share/bios/                    ## BIOS files, placed flat

Rationale: name resolution is the flaky part of this. If \\BATOCERA\share does not appear, fall back to the machine's IP address, which you can read off Batocera's network settings menu. A wired Ethernet connection is both faster for bulk copying and less likely to drop mid-transfer than Wi-Fi, which matters when you are moving tens of gigabytes of disc images.

The folder layout, and _info.txt

Everything lives under /userdata, and the structure is rigid on purpose: one folder per system, named by Batocera's short code for that system, with games dropped directly inside. Guess the folder name and your games become invisible. Fortunately every system folder ships a self-documenting _info.txt that tells you exactly which file extensions that emulator will accept.

/userdata/                     ## writable partition (auto-expanded on 1st boot)
  roms/                        ## games, one folder per system short-name
    snes/                      ## Super Nintendo  (read its _info.txt)
      _info.txt
    nes/
    n64/
    psx/
    megadrive/
  bios/                        ## BIOS / firmware -- you supply these
    scph5501.bin               ## PS1 (US) -- exact hash matters
  saves/                       ## save files and save-states
  system/                      ## batocera.conf lives here
    batocera.conf

When a system won't recognise a game, the first thing to check is that the file's extension is on the accepted list. Reading the _info.txt takes ten seconds and settles the question:

$ cat /userdata/roms/snes/_info.txt
Super Nintendo Entertainment System
Accepted ROM extensions: .smc .sfc .swc .fig .bs .st .zip .7z
Place ROMs directly in this folder; sub-folders are ignored by default.

After copying games in, tell EmulationStation to rescan by going to START -> GAME SETTINGS -> UPDATE GAMELISTS. Rationale: Batocera builds its menus from a cached gamelist, not by scanning the disk on every boot, so freshly copied ROMs stay invisible until you trigger a refresh. This one menu item resolves the overwhelming majority of 'I copied the games but the system is empty' reports.

BIOS: where the law and the lore meet

BIOS files are the last mile and the most fiddly, because they are hash-checked. A file named correctly but with the wrong bytes counts as missing, and Batocera will tell you so. The system menu has a dedicated MISSING BIOS screen that lists, per system, exactly which files are absent and what their checksums must be; treat it as a shopping list. Cross-reference it against the Batocera games and BIOS wiki and the libretro BIOS reference so you place the right revision. Place BIOS files flat inside share/bios/ unless a system's info file says otherwise. Rationale: sourcing these is your responsibility and your legal exposure, and the project cannot help you there. What it can do is verify, once the file is present, that it is the correct one, which is why matching the hash matters more than matching the name.

Five Pitfalls That Cost an Afternoon

Every one of these has consumed someone's evening on a forum. None of them needs to consume yours.

Pitfalls 1 and 2: wrong architecture, and the black screen it causes

The pitfall: downloading the plain x86_64 image for a Raspberry Pi, or a bcm2711 image for a laptop, and getting either nothing at all or a black screen after the splash. The fix: re-read the architecture table above, confirm the token in your filename matches your device, and re-flash with the correct image. A related black-screen cause on PCs is a GPU the default drivers do not like; Nvidia support in the 43.x line is still marked experimental, so an all-black boot on an Nvidia machine is a known rough edge rather than a broken download. Where a choice exists, an AMD or Intel iGPU gives Batocera the smoothest ride.

Pitfall 3: the 16 GB cliff and the SD card lie

The pitfall: installing to a drive under 16 GB and then finding you cannot update, or buying a suspiciously cheap '256 GB' SD card off a marketplace that is really an 8 GB card lying about its size. Batocera disables its in-place updater below 16 GB, and a fake card corrupts data silently once you cross its real capacity. The fix: use a genuine card of at least 16 GB, 32 GB recommended, from a vendor you trust, and verify a suspicious card's real capacity with a tool like f3 or H2testw before you commit games to it. The first boot's userdata expansion assumes the drive is as large as it claims; a lying card turns that assumption into corruption.

Pitfalls 4 and 5: v43's breaking changes and the flashing shortcut

The pitfall: upgrading to the 43 line and finding your Nintendo DS saves gone, your 3DS games refusing to launch, or a game copy failing because you dragged the .img.gz onto the stick in a file manager instead of flashing it. Batocera 43 dropped the DraStic DS emulator in favour of melonDS, and those save files do not transfer between the two. It also now requires 3DS ROMs to be decrypted, re-supporting the .3ds format but shipping with hardware shaders off by default, so an encrypted dump simply will not run. And a file-manager copy of the image never produces a bootable drive. The fix: keep your old DraStic saves but expect to restart those specific games; decrypt 3DS titles before copying them and leave the shader default alone until things work; and always write the image with a real flashing tool, never a drag-and-drop. These are documented behaviour changes, not bugs, which means they will not be 'fixed' in a later patch.

Troubleshooting: Eight Failures

When something breaks, resist the urge to re-flash immediately. Most of these have a targeted fix that takes a minute, and re-flashing to fix a gamelist problem is like buying a new car because the radio preset changed.

Boot and display failures

These are the ones that stop you cold at the beginning, before you ever reach a menu. Nearly all of them trace back to firmware settings or a mismatched image rather than a bad drive, which is why the first two fixes below are 'check the UEFI' and 'check the filename' rather than 'buy a new stick'.

Controllers, audio, and games that will not launch

These arrive after a successful boot, when the system is up but a specific piece of it misbehaves. They are almost always configuration or content problems, which means they are cheap to fix once you know where to look.

If a fault survives all of this, the logs will tell you why, and the next section is how you read them.

Advanced Tips: SSH and Upgrades

Once the console works, Batocera rewards a little command-line curiosity. None of this is required, but all of it turns 'it's broken and I don't know why' into 'it's broken and here is the exact line that says so'.

SSH in and read the logs

Batocera runs an SSH server by default, and the default credentials are root / linux. Change that password the moment the machine is on a network you share with anyone, because 'root / linux' is not a secret. Once in, you can query the hardware, confirm the version, and, crucially, read the launch log when a game fails silently:

## default login is root / linux -- change it immediately:
ssh root@BATOCERA.local
passwd

## which board, which version am I actually on:
batocera-info
cat /boot/boot/batocera.board

## when a game refuses to launch, the reason is in here:
tail -n 60 /userdata/system/logs/es_launch_stdout.log

Rationale: EmulationStation swallows emulator errors behind a generic 'failed to launch' flash, but the underlying core almost always writes a specific complaint to the log first: a missing BIOS by name, an unsupported ROM format, a core that crashed on load. Reading sixty lines of log beats sixty minutes of guessing. Batocera's cores are the same libretro cores you would tune by hand in a standalone RetroArch setup, so if you want to understand what is actually running under the hood, our breakdown of the core catalogue maps the territory.

Upgrade in place, and roll back

Batocera updates itself without re-flashing, which is a large part of why it beats maintaining a hand-built stack. From the menu it is UPDATES; from the shell it is one command. The manual path, for machines that cannot reach the internet or that you want to pin to a specific build, drops a boot.tar.xz into /userdata/system/upgrade and runs the upgrade against it, pulling from the project mirror at mirrors.o2switch.fr/batocera.

## in-place upgrade to the latest stable:
batocera-upgrade

## expected: it reports installed and available versions, then downloads
## Checking version ...
## Current version: 43.1
## A new version is available: ...
## downloading ...

Rationale: the in-place upgrader preserves your /userdata -- games, saves, and config all survive -- which is exactly why the 16 GB storage floor exists: below it, the updater refuses to run. If an upgrade ever regresses something you rely on, the same mechanism supports installing a specific older build from the mirror, which is the sane version of 'rolling back' that does not involve re-flashing from scratch. The manual upgrade wiki page documents the pinning procedure in full.

batocera.conf: edit once, apply everywhere

Every setting the menus expose is ultimately a line in a single file, /userdata/system/batocera.conf. Editing it directly -- over SSH, or by mounting the share -- is faster than clicking through menus when you are configuring several systems at once, and it is the only sane way to keep a backup of your preferences. The syntax is plain key=value, with global settings under global. and per-system overrides prefixed by the system's short name. Rationale: because this one file holds your entire configuration, copying it somewhere safe means a future re-flash is a thirty-second restore rather than an evening of re-tuning. The full key reference lives on the batocera.conf syntax wiki, and the next section is a complete, commented example you can adapt.

A Complete Working Configuration

Here is a full, working baseline: a sensible batocera.conf, the folder tree it assumes, and a five-minute test to confirm the whole thing actually plays a game. Adapt the values to taste; the structure is what matters.

The batocera.conf

## /userdata/system/batocera.conf -- global settings first, overrides below
## Full key reference: wiki.batocera.org/batocera_conf_syntax

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

## --- Updates ---
updates.enabled=1
updates.type=stable            ## stable | butterfly (beta). Keep stable.

## --- Network ---
wifi.enabled=0                 ## set to 1 and fill ssid/key to use Wi-Fi
## wifi.ssid=YourSSID
## wifi.key=YourPassword

## --- Video / audio (global defaults) ---
global.videomode=default
global.smooth=1                ## bilinear smoothing
global.rewind=1                ## costs RAM/CPU -- set 0 on weak boards
global.autosave=0
global.integerscale=0
global.shaderset=none          ## none | scanlines | retro
audio.volume=90

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

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

## --- Per-system overrides: short-name + .core (examples) ---
## Pull the exact core string from the per-game menu; these are illustrative.
snes.core=snes9x
nes.core=fceumm
n64.core=mupen64plus-next
psx.core=swanstation
megadrive.core=genesisplusgx

A word on those per-system core lines: the exact short-name strings are visible in the per-game menu under each title, and they occasionally shift between releases, so treat the block above as a template rather than gospel and confirm each string against your running system. The global block, by contrast, is stable and safe to copy verbatim.

The folder tree that just works

/userdata/
  roms/
    snes/       your-legally-dumped.sfc
    nes/        your-legally-dumped.nes
    n64/        your-legally-dumped.z64
    psx/        game.chd            ## + BIOS in bios/
    megadrive/  your-legally-dumped.md
  bios/
    scph5501.bin                    ## PS1 US -- hash-checked
    (whatever MISSING BIOS lists)
  saves/                            ## fills in as you play
  system/
    batocera.conf                   ## the file above

Rationale: this is the layout every emulator in Batocera expects, and matching it exactly is what makes the difference between a menu full of games and a menu that stubbornly reads 'no games found'. The psx line is a reminder that disc-based systems need both the game (a .chd is a compressed disc image) and their BIOS in place, or the core throws its red warning.

The five-minute smoke test

To confirm the whole stack works end to end before you invest hours curating a library: copy one small, uncontroversial ROM into its system folder -- an 8-bit or 16-bit game with no BIOS requirement is ideal -- run UPDATE GAMELISTS, and launch it. If it boots to gameplay and your controller moves the character, every layer is verified at once: the image was correct, the flash was clean, the install booted, the share works, the folder name was right, and the core runs. Rationale: testing with a simple, BIOS-free game isolates the plumbing from the content. If that game runs and a PS2 title does not, you know the problem is BIOS or horsepower, not your installation. From here, scaling up is just more of the same folders -- and if you ever decide the software-emulation road is not for you, our comparison of the frozen-in-time RetroPie project is a useful map of the alternative distributions and where each one has quietly stopped moving.

That is the entire download-to-gameplay path: pick the image that matches your board, write it with a real tool, boot past Secure Boot, optionally install to disk without erasing the stick you booted from, and supply the games and BIOS files that Batocera will never ship. Do those in order and the black screen never happens. Skip the architecture step and it always does.