Goal: Update Batocera to the latest stable release without breaking anything.
1) Quick prep (recommended, but easy)
- Connect Batocera to your network (Wi-Fi or Ethernet).
- Free space: make sure you have a few GB free on your storage (updates need room to download). If you’re tight on space, delete a few large ROMs temporarily.
- (Optional) Backup your saves/configs: From another computer on the same network, open the \BATOCERA\ network share (Windows) or smb://batocera/ (macOS/Linux) and copy the /saves and /system folders somewhere safe. This is just in case.
2) Make sure you’re on the “Stable” track
- On Batocera’s main game list, press START to open the Main Menu.
- Go to Updates & Downloads → Update Type and choose Stable.
- “Stable” = normal releases.
- “Beta/Butterfly” = test builds (not recommended if you’re new).
Tip: You can switch tracks any time in the same menu.
3) Do the update (the normal way)
- Main Menu → Updates & Downloads
- Select Check for Updates (Batocera will look for the newest stable version).
- If an update is found, select Start Update → confirm.
- Wait for the download + install to finish, then reboot when prompted. Done!
4) Verify the new version (optional)
After reboot: Main Menu → System Settings → Information to see your Batocera version number.
You can compare it with the latest entry on Batocera’s official Changelog page if you like.
5) If the built-in updater fails (rare)
You can force an upgrade manually—handy if mirrors are busy or you need a specific version.
Option A — One-command upgrade (SSH)
- Enable SSH in System Settings (if not already).
- From a PC on your network, SSH into Batocera and run:
batocera-upgrade
This downloads, verifies, and installs the correct update for your device, just like the GUI does. Reboot when it’s done.
Option B — Upgrade to a specific version (advanced)
If you absolutely must jump to a particular version, you can point batocera-upgrade at that version’s folder on a mirror. Example:
batocera-upgrade https://mirrors.o2switch.fr/batocera/x86_64/stable/last/archives/36/
(Replace the URL with the right architecture/version.)
Reboot after it completes.
6) Common questions
- Will I lose my games/saves?
No—updates replace system files, not your userdata. Your ROMs, saves, and themes stay. (Still, backing up saves is smart.)
- How do I get notified of new updates?
In Updates & Downloads, Check for Updates/notifications work based on your Update Type (keep it on Stable).
- Where do I see what changed?
Batocera’s official Changelog lists highlights per release.
- Can I switch from Beta back to Stable?
Yes: Update Type → Stable, then run the update again. You can also set it via updates.type in batocera.conf, but the menu is easiest.
7) Quick troubleshooting
- Stuck or no update found:
Confirm Update Type = Stable, check internet connection, try again later, or use batocera-upgrade via SSH.
- Not enough space:
Temporarily move a few large ROMs off the card/drive, then retry. Updates need a few GB to download/verify.
- Power loss during update:
Rarely harmful, but if it boots oddly, run the updater again once power is stable. (Manual upgrade page explains recovery paths.)
8) Useful official links
That’s it!
Keep Update Type = Stable, run Check for Updates → Start Update, reboot, and enjoy. If anything misbehaves, the manual upgrade guide + batocera-upgrade command have your back.
