00 Install
01 First Boot
02 SSH
03 Storage
04 BIOS
05 Emulators
06 Cache
07 Recovery
08 Performance
09 Gotchas

v2.1 — AMD & High-End Emulation

Batocera Setup & Survival Guide

Covers: installation to a USB or SSD · first boot configuration · SSH access and common fixes · storage hygiene · BIOS files · emulator-specific settings for PS3, Switch, Xbox 360, Wii U · shader cache management · emergency recovery · performance troubleshooting.

// 00

Installing Batocera

What you need

A USB drive or dedicated SSD — minimum 16GB, 64GB+ recommended for high-end emulators
Batocera image — download the x86_64 build for PC
Balena Etcher or Rufus to flash the image

Flashing the image

Flash with Etcher: Open Etcher → Flash from file → select the .img.gz → select your USB/SSD → Flash. Do not extract the archive first.

Rufus alternative: Select device → Image option: DD Image mode → Start. If Rufus asks about ISO or DD mode, choose DD.

Boot from USB: Enter your motherboard BIOS (usually F2, F12, or Delete on startup) → set USB as first boot device → disable Secure Boot.

Install to internal drive (optional but recommended): Once booted, press F1 in Batocera → System Settings → Install Batocera on a new disk. This copies Batocera to a dedicated internal drive for better performance and persistence.

⚠ Partition warning

Batocera’s installer will wipe the target drive completely. If you are installing to an internal SSD, confirm it is the correct drive before proceeding. The partition layout is fixed — Batocera manages it automatically.

Drive sizing decisions

16–32GB: Fine for pre-PS2 era only. No room for PS3 or Switch.
256GB–1TB: Comfortable for PS2, GameCube, Wii, and some PS3 titles. Leave 15% free at all times.
2TB+: Required for a meaningful PS3 or Switch library. Keep 50–100GB free minimum.

// 01

First Boot Configuration

Immediate checks

Controller detected and working — press Start to confirm in the main menu

Display resolution correct — Main Menu → UI Settings → Resolution

Network connected — Main Menu → Network Settings → enable Wi-Fi or confirm Ethernet

Note your IP address — shown in Network Settings. You need this for SSH.

Enable SSH — Main Menu → System Settings → Services → SSH: ON

Key settings to change before adding ROMs

Disable Video Previews: UI Settings → Video Previews → Off. These continuously read from disk and cause menu lag on large libraries.

Set your audio output: Sound Settings → select the correct output device. HDMI audio defaults are unreliable on some AMD setups — switch to DisplayPort if available.

Check for updates: Main Menu → Updates & Downloads → Start Update. Do this before adding any ROMs. Updating after a large library is populated is slower.

Check disk space immediately after updating: Via SSH, run df -h /userdata. Updates on a near-full drive will corrupt shader caches (see Section 06).

Note

The /userdata partition is where all your ROMs, saves, configs and caches live. The system partition is separate and smaller. Space warnings in Batocera’s UI refer to /userdata, not total disk space.

// 02

SSH — Direct System Access

SSH gives you command-line access to Batocera from another PC on the same network. It is the primary tool for fixing problems, managing files, and checking system state when the UI is unresponsive or the screen is black.

Connecting

# On Windows: use PowerShell, Windows Terminal, or PuTTY
# On Mac/Linux: use Terminal

ssh root@YOUR_IP_ADDRESS

# Password: linux
# No characters display as you type the password — this is normal

⚠ Before making any system changes

Always run this first to allow writes to the boot partition:

mount -o remount,rw /boot

Without this, changes to boot config files silently fail or cause read-only errors.

Essential commands

# Check disk usage
df -h /userdata

# Find your largest directories
du -sh /userdata/*/ | sort -h

# Find your IP address from within Batocera
ip a

# List files in a directory
ls -lh /userdata/roms/ps3/

# Delete a specific file or folder
rm -rf "/userdata/roms/ps3/GAMEFOLDER"

# Restart EmulationStation without rebooting
systemctl restart batocera-es

# Full reboot
reboot

Transferring files over the network

Batocera exposes a Samba share on your local network. Open your file manager on Windows (\\BATOCERA) or Mac (smb://batocera) to drag ROMs and BIOS files directly. This is faster than SSH for bulk transfers.

SSH from Windows without PuTTY

Windows 10 and 11 include a built-in OpenSSH client. Open PowerShell or Command Prompt and type ssh root@YOUR_IP — no additional software needed.

// 03

Storage & The Ghost Data Problem

High-end emulators — PS3, Switch, Xbox 360, Wii U — are write-heavy. They install data, create caches, and write save states constantly. This data accumulates independently of the ROM files themselves.

The 5% free space rule

Linux filesystems degrade when full. GPU drivers cannot write shaders. The system throttles to handle disk errors. Performance collapses — often confused with an emulator bug or a bad update.
On a 2TB drive: keep 50–100GB free minimum at all times.
On a 500GB drive: keep 25GB free minimum.
Check regularly: df -h /userdata — the “Use%” column should stay below 90%.

PS3 — installed game data

Deleting a PS3 ROM does not delete the data RPCS3 installed for that game (firmware updates, DLC, internal game data). This lives separately:

/userdata/system/configs/rpcs3/dev_hdd0/game/

Each subfolder corresponds to a game’s internal ID (e.g. BLES01807). If you have deleted the ROM, the installed data is orphaned and still consuming space. Identify and delete the matching folders manually.

Switch — shader and pipeline caches

/userdata/system/configs/yuzu/shader/
/userdata/system/configs/yuzu/cache/

Shader caches grow over time and can reach several GB per game. If a game is removed, its cache directory remains. Periodically audit this folder.

Xbox 360 — Xenia write data

/userdata/system/configs/xenia/cache/

Critical

If your drive hits 100% while a game is actively running, the shader cache file for that session will corrupt. The next launch of that game will stutter or freeze at the same point every time. Clearing the cache (Section 06) is the fix.

// 04

BIOS Files

Many emulators require dumped firmware from the original console hardware. Batocera does not include these files — you must supply them. Incorrect or incomplete BIOS files cause crashes-to-menu or failure-to-launch, with no clear error in the UI.

Where to put BIOS files

/userdata/bios/

File names and paths are case-sensitive. A file named SCPH1001.BIN and one named scph1001.bin are not interchangeable on a Linux filesystem.

Verifying BIOS integrity

Main Menu → System Settings → Missing BIOS. This shows which files are absent or have incorrect checksums.

A red entry means the file is either missing, misnamed, or corrupted. Replace it — do not attempt to rename a wrong file to match.

Cross-reference required BIOS file names against the Batocera BIOS wiki — the wiki lists exact filenames and MD5 checksums for each system.

High-end emulator firmware

PS3 (RPCS3): Requires PlayStation 3 firmware (PS3UPDAT.PUP) installed via RPCS3’s File → Install Firmware menu.
Switch (Yuzu): Requires firmware keys (prod.keys, title.keys) in /userdata/system/configs/yuzu/keys/. Without correct keys, encrypted titles will not launch.
Wii U (CEMU): Does not require external firmware but needs game files in the correct directory structure (unpacked WUD or NUS format).

⚠ Firmware versions matter

RPCS3 in particular is sensitive to PS3 firmware version. Use the latest official PS3 firmware file. Older firmware versions cause compatibility failures with newer game titles that require specific system modules.

// 05

Emulator-Specific Setup

PS3 — RPCS3

ROMs go in /userdata/roms/ps3/ as folders (not ISO files). Each game is a directory containing PS3_GAME and related subfolders.
Right-click a game in RPCS3 → Create Custom Configuration. Per-game settings dramatically affect compatibility — check the RPCS3 compatibility list for recommended settings per title.
Vulkan renderer performs significantly better than OpenGL on AMD hardware. Set this in GPU settings for each game config.
PPU and SPU recompiler caches are stored in /userdata/system/configs/rpcs3/cache/. First launch of a game compiles these — expect 2–10 minutes of initial load time.

Switch — Yuzu

ROMs: .nsp, .xci, or .nca format in /userdata/roms/switch/.
Keys must be current — if a game decryption error appears, your keys are outdated for that title’s firmware requirement.
Vulkan backend recommended on AMD. OpenGL has lower overhead for some titles but generally worse performance on AMD GPUs.
Updates and DLC are installed via File → Install Files to NAND within Yuzu. Do not place update NSPs in the ROMs folder as standalone entries.

Xbox 360 — Xenia

ROMs as .xex or extracted XBLA format folders in /userdata/roms/xbox360/.
Vulkan backend only — D3D12 is not available on Linux. Performance depends heavily on per-game compatibility.
Many titles that run at full speed on Windows via Xenia Canary may not perform equivalently under the Batocera-bundled Xenia version. Check the Xenia compatibility list before expecting specific titles to run.

Wii U — CEMU

Requires games in unpacked format (folder with code, content, meta subfolders) in /userdata/roms/wiiu/.
Graphic packs (mods and resolution upscales) are managed within CEMU settings — these are separate from Batocera’s interface.
Vulkan renderer recommended. The Async Shader Compile option in CEMU settings eliminates the worst stutter during shader compilation.

// 06

Clearing Corrupted Caches

If a drive hits 100% while a game is running, the shader cache file for that session corrupts. Symptoms: game stutters at the same point every time, audio delays, or immediate crash on launch. Clearing forces a clean rebuild on next launch — expect a longer first-load time while compilation runs.

System	What’s cleared	SSH command
AMD GPU	Mesa shader cache (system-wide)	rm -rf /userdata/system/.cache/mesa_shader_cache
PS3 (RPCS3)	PPU/SPU compiled modules	rm -rf /userdata/system/configs/rpcs3/cache/*
Switch (Yuzu)	Vulkan shader pipelines	rm -rf /userdata/system/configs/yuzu/shader/*
Xbox 360	Xenia pipeline cache	rm -rf /userdata/system/configs/xenia/cache/*
Wii U (CEMU)	Graphic pipeline cache	rm -rf /userdata/system/configs/cemu/shaderCache/*

After clearing

The first launch after clearing will take significantly longer than normal — this is the compilation phase running from scratch. Do not interrupt it. Once complete, frame rate returns to normal and subsequent launches are fast.

⚠ AMD Mesa cache and updates

Every Batocera update that changes the Mesa driver version effectively invalidates your existing Mesa shader cache. If post-update performance is poor, clear the Mesa cache first before investigating anything else.

// 07

Emergency Recovery

Black screen on boot, system unreachable from the UI. Power is on — SSH is still accessible. Run these in order.

Unlock boot partition

mount -o remount,rw /boot

Required before any other change. Without this, all writes to /boot silently fail.

Check disk space first

df -h /userdata

If “Use%” is at or near 100%, that is almost certainly the cause. Free space before doing anything else (see step 04).

Force video output (if display is blank)

echo “es.videooutput=HDMI-A-1” >> /boot/batocera-boot.conf

Replace HDMI-A-1 with your actual output — check with: batocera-resolution listOutputs. Common values: HDMI-A-1, HDMI-A-2, DisplayPort-1.

Find and delete space hogs

du -sh /userdata/roms/ps3/* | sort -h

Repeat for other large emulator folders. Delete with: rm -rf "/userdata/roms/ps3/GAMEFOLDER". Target at least 40GB free before rebooting.

Reset EmulationStation config (if UI is corrupt)

rm /userdata/system/configs/emulationstation/es_settings.cfg

Resets UI settings to default. ROMs, saves, and game configs are unaffected. Only do this if ES itself is the problem.

Clear shader caches

rm -rf /userdata/system/.cache/mesa_shader_cache

Do this if the system boots but games still stutter or crash after freeing space.

Reboot

reboot

After reboot, verify disk space again immediately: df -h /userdata.

If SSH itself is unreachable

If SSH is not responding but the system is powered on, the most likely causes are: network not connected (check router), SSH service disabled, or kernel panic from a full disk on boot. Boot from a second USB with Batocera to mount and repair the drive.

// 08

Performance Diagnostics

Thermal throttling

If FPS is stable for 10–15 minutes and then drops to roughly half — not gradually, but suddenly — the CPU or GPU is throttling due to heat. AMD chips under PS3 emulation load generate significant heat.

Via SSH: watch -n 1 cat /sys/class/hwmon/hwmon*/temp*_input — temperatures above 90°C on any sensor indicate thermal throttling is occurring.

Check that cooler fans are spinning. Batocera does not always trigger fan curves the same way as Windows. AMD iGPUs sharing the CPU heatsink are particularly prone to this.

Check case airflow. Batocera runs emulators closer to hardware limits than typical desktop workloads — a system that runs fine in Windows may throttle under sustained emulation load.

AMD GPU — Mesa Vulkan vs OpenGL

Batocera uses Mesa (open-source AMD drivers) — not AMDGPU-PRO. Performance characteristics differ from Windows.
For PS3, Switch, and Xbox 360: Vulkan backend consistently outperforms OpenGL on AMD hardware in Mesa. Set this explicitly in each emulator’s settings rather than relying on defaults.
Shader pre-compilation on first launch is a Mesa behaviour, not an emulator bug. It is longer on Linux than Windows due to the shader cache format difference.

Menu performance

Video Previews ON: Batocera continuously reads video files from disk while you browse. On large libraries this saturates disk I/O and causes constant CPU/disk activity even at rest.
Large scraped media: If you have scraped box art and videos for thousands of games, the EmulationStation database becomes large. Disable video previews; keep images as the only scraped media type if needed.

Constant stutter

Check disk space first. Then Mesa shader cache. Then thermals. In that order.

Crashes to menu

Missing or corrupt BIOS. Check System Settings → Missing BIOS. Also check per-game emulator config.

Black screen on launch

Wrong video output set, or emulator crashed before display initialised. Check SSH logs: journalctl -b -n 100

Slow menu only

Disable Video Previews. If still slow: too many scraped media files — reduce scrape to images only.

// 09

Common Gotchas

Updates on near-full drives

Batocera updates download to /userdata before applying. If the drive is over 85% full, the update download can push it to 100%, corrupting the Mesa cache and sometimes the update itself. Always check df -h /userdata and ensure at least 10–15GB free before updating.

Case-sensitive file system

Batocera runs on a Linux filesystem — case matters. scph1001.bin and SCPH1001.BIN are different files. BIOS files especially must match the exact filename specified in the Batocera wiki, including capitalisation. Check the wiki, do not guess.

PS3 ROM format

RPCS3 requires games as directories, not ISO files. If a PS3 game is showing as unrecognised, the directory structure is likely wrong. Each game folder must contain PS3_GAME/ at minimum. Compressed or single-file formats do not work.

Saves and states live in /userdata

If you reinstall or reflash Batocera, /userdata is preserved only if you specifically choose not to format it. Reinstalling to the same drive via the Batocera installer will format /userdata by default. Back up saves to a separate location via SSH or Samba before any reinstall.

Controller mapping per emulator

Batocera’s controller mapping in the main menu applies to RetroArch-based emulators. Standalone emulators (RPCS3, Yuzu, CEMU, Xenia) manage their own controller configs independently. If a controller works in the menu but not in a game, the issue is the per-emulator controller config, not Batocera’s mapping.

SSH root password

The default SSH password is linux. If you change this via System Settings → Security, write it down immediately. There is no password recovery path without booting from a second drive and manually editing the shadow file.

Wii U game format

CEMU requires Wii U games in unpacked (folder) format — not WUD, not ISO. The correct structure has code/, content/, and meta/ folders. Placing a single large image file in the roms folder will not work.

✓ Before reporting a “bug”

Check in this order: disk space → shader cache integrity → BIOS files → thermals → per-emulator settings. The majority of issues reported as Batocera bugs or emulator regressions are one of these five things.

Batocera Emulation Setup & Survival Guide