This version is outdated by a newer approved version.DiffThis version (2021/09/10 09:30) is a draft.
Approvals: 0/1

This is an old revision of the document!


Manual upgrades/downgrades

This is for if you:

  • can't upgrade/downgrade from stable to beta or vice versa using MAIN MENU > UPDATES & DOWNLOADS > UPDATE TYPE > “Stable” or “Beta” and updating,
  • want to downgrade to an older revision,
  • want to install a custom version of Batocera,

To upgrade/downgrade manually:

  1. Download the boot.tar.xz file of the version you want. The official ones are available at http://batocera.org/upgrades (for older versions use https://mirrors.o2switch.fr/batocera/, navigate to your architecture and go to /stable/last/archives/).
  2. Unzip the .tar.xz file (it's just like a .zip, you can use 7-zip on Windows) into the root of your Batocera drive's boot partition (This is the default partition you see when inserting the drive into Windows) and overwrite the existing files. You may have to assign a drive letter under Windows Disk Management to see it in the file explorer.

Alternatively (from Batocera 5.23 onwards) you can do this from SSH. Get the URL to the right architecture's last folder and run batocera-upgrade [URL]. For example, a x86_64 platform would run

batocera-upgrade https://batocera.org/upgrades/x86_64/stable/last

You should then see output similar to this:

Starting the upgrade...
url: https://updates.batocera.org/x86_64/stable/last/boot.tar.xz
need to download 1876mb
m/upgrade/boot.tar.xz     0%[                              ]   9.55M  1.82MB/s    eta 19m 42s

For Batocera 5.7 to 5.22, the command (for PC x86_64, please adapt to the right architecture) would instead be:

/recalbox/scripts/recalbox-upgrade.sh https://batocera.org/upgrades/x86_64/stable/last

These commands download the compressed upgrade (or potentially downgrade) file and expand it to overwrite the Batocera system on the boot partition. Upgrading or downgrading like this doesn't remove any of your user data (ROMs, saves, metadata…). Like never, ever.

If you get an error message telling you that you don't have enough space on your Batocera boot partition while attempting to upgrade, there might be several reasons:

  1. Your drive is less than 8GB total. Batocera can run on these drives but you will be missing out on using the built-in updater.
  2. The splash video file(s) (which are copied to the /boot partition) are/is taking up too much space. Remove them/it, reboot and try to upgrade again.
  3. Your first installation was an older version of Batocera, where the /boot partition was initially assigned less space (compared to installations of newer Batocera versions).

To work around this, you can any one of the following:

  • Insert your drive into another computer, back up the contents of the FAT32 boot partition of the drive (Windows should only be able to see this partition and nothing else by default), delete the /boot/batocera file (it is just called batocera without a file-extension and is about 2 GB large (smaller in older versions)) and extract the boot.tar.xz file to the root of that partition. Rename the freshly extracted /boot/batocera file to batocera-update, then boot Batocera. Be aware that by doing this you would have to do this manual workaround every time you need to update.
  • Boot into Batocera, SSH in or use the file manager's xterm and run the following:
    mount -o remount,rw /boot

    Backup your /boot/boot/batocera file to another device (cp /boot/boot/batocera /userdata/system/batocera-backup, or you can exit the xterm with Alt+F4 and then use the file manager to copy the file to your /userdata/system folder). Then run the following command to delete the batocera file and immediately upgrade:

    rm -i /boot/boot/batocera && batocera-upgrade

    Confirm the file you want to delete. You should then get an output that looks like this:

    Starting the upgrade...
    url: https://updates.batocera.org/x86_64/beta/last/boot.tar.xz
    need to download 1876mb
    m/upgrade/boot.tar.xz     0%[                              ]   9.55M  1.82MB/s    eta 19m 42s

    Be aware that by doing this you would have to do this manual workaround every time you need to update.

  • Flash a spare USB/portable hard-drive with a new copy of Batocera and boot into that, copy all your /userdata (everything in Share) from your old Batocera drive to your spare USB/portable hard-drive and then reflash the old Batocera drive with a new version of Batocera (or just continue to use your spare USB/portable hard-drive).
  • Backup your /userdata to another device (you may lose file attributes by doing this, causing problems with WINE/Cemu) and reflash Batocera.
  • Extend the boot partition of your drive using an advanced tool like gparted or Gnome Disk Utility. This will likely destroy your userdata partition, so back up all your ROMs, saves, configs, etc. first. This is not the recommended method, as there is no way to know how far you should extend your partition, it may cause irreversible damage to your drive and it may damage the MBR/GPT table, causing the drive to become unbootable. Consider the other options first.

An illustration showing how the batocera system is laid out on a USB stick: the BATOCERA partition first, containing all the programs, and then the SHARE, containing all the userdata

  • upgrade_manually.1631259026.txt.gz
  • Last modified: 3 years ago
  • by atari