Batocera Updates and Recovery: Protect Userdata Across System Changes

Batocera separates the operating system from most of the user’s library and settings. That design makes a system upgrade easier to reason about than replacing one monolithic installation, but it does not make every upgrade risk-free. The boot partition can be rewritten, architecture-specific images are not interchangeable, and user data still needs an independent backup.

This runbook covers the release-selection, backup, upgrade, and recovery boundaries. It does not provide game images or firmware. Use only software and system files you are authorized to use, and keep unmodified preservation copies separate from files used for testing.

Understand what is replaced

Batocera documents two principal partitions. The boot partition contains the files needed to start the system; the userdata partition (also called Share) holds ROM folders, BIOS files, saves, user configuration such as batocera.conf, and related data. Normal upgrades replace system files while preserving userdata. This separation is useful, not a backup guarantee: storage can fail, a manual procedure can be misapplied, and a new emulator version can change how it interprets an existing save or configuration.

Before an upgrade, write down the device model, Batocera architecture/build, current release, update channel, and any boot options you changed. Do not infer the architecture from the processor label or copy an x86-64 example URL onto a single-board computer. Use the build information on the device and the official release page for that exact target.

Choose a release deliberately

Batocera exposes stable and development-oriented update channels. Stable is the conservative choice for a console expected to work; the development channel exists for testing newer work and may carry regressions. Record the selected channel and exact version before proceeding. When you need a known rollback target, obtain its URL from Batocera’s own release listing and confirm that it matches the device architecture.

Do not mix package managers or install ordinary Linux packages into the appliance to solve an emulator issue. Batocera’s root filesystem and update model are project-managed; a hand-modified system file may disappear on reboot or be replaced by the next update. Keep customization in documented persistent locations.

Make a recovery copy before writing

Back up the complete userdata partition to a second physical device or trusted backup target. Include the entire content tree rather than just the ROM folder: saves, save states, BIOS/system files, controller profiles, themes, scraped metadata, and system configuration can all matter to recovery. Keep any copyrighted content private and do not attach firmware or game data to public bug reports.

If you edited boot configuration, save the relevant boot files separately as well. A file copy can omit filesystem metadata needed by some applications; Batocera specifically warns that copying userdata through an unsuitable filesystem or host may lose file attributes that affect Wine or Cemu. Prefer a backup path that preserves the source filesystem’s relevant attributes, and verify that a sample directory, save, and configuration file can be restored. Keep the backup unchanged while testing the upgrade.

Record the backup date, source device, release, target architecture, and a manifest of file names, sizes, and cryptographic hashes for irreplaceable saves or configuration. A hash detects later byte changes when compared with a trusted manifest; it does not prove that the original data was correct.

Apply the supported update path

Use Batocera’s built-in updater for ordinary upgrades. Its documented process downloads a boot image into the persistent upgrade area, checks the downloaded file, updates the boot files, preserves boot configuration, and cleans up. Keep stable power and enough free space available; do not remove the storage device during download, writing, or the first reboot.

If the built-in updater cannot be used, follow the current manual-upgrade page from start to finish. Batocera documents version-specific caveats around manual extraction and boot configuration; some manual paths can resize or overwrite userdata under particular boot settings. Do not improvise by extracting a system archive over the boot partition, and do not skip the documented backup and boot-config steps. An incomplete boot update can make the device unbootable even when userdata remains intact.

Verify behavior before deleting the rollback point

After the system starts, verify the displayed Batocera version and architecture, then test a small representative set:

Confirm the expected systems and game paths appear.
Launch one known-good title per emulator family that matters to you.
Test controller mapping, audio, display mode, and clean return to the frontend.
Create a native in-game save, shut down through the system menu, reboot, and load that save.
Check a multi-disc title or other special format if your collection depends on one.
Inspect logs for a failed emulator launch or missing file before treating the upgrade as complete.

Do not validate only with a save state: save states can depend on a particular emulator/core version and are not a substitute for the game’s own saved data. If a title fails only after the upgrade, record the title’s lawful content hash, emulator/core version, and error log, then test the prior known-good release using the documented rollback procedure. Avoid changing multiple emulator settings at once.

Treat reinstallation as a separate operation

Reflashing a device is not equivalent to an in-place update. The imaging process can erase the selected drive, so identify the target by model and capacity, disconnect unrelated removable disks if practical, and recheck it immediately before writing. Restore userdata only after the new system boots correctly and the target’s filesystem is understood. Preserve the original backup until representative games, saves, and configuration have passed the recovery test.

The maintenance is complete when the release target is documented, userdata and boot configuration have independent verified backups, the device starts the intended build, representative games and native saves work after a cold restart, and a rollback path is known. A successful version screen alone proves only that the operating system started.

Related:

Sources: