Installation Guide

For those who prefer video guides, here are some excellent ones by ETA Prime: Turn An Old Cheap PC Into An Emulation Dream Machine! for x86_64 computers (the controller configuration for standalone emulators at 18:27 is outdated, Batocera now handles controller configuration for you. For customizing controls per emulator, check this page) and Install Batocera On The Raspberry Pi 4 Full Setup Guide - Retro Gaming Goodness! for single-board computers.

You can check out which devices Batocera supports running on at the supported devices page!

Generic instructions for most platforms are as follows:

  1. Download Balena Etcher for your operating system (Raspberry Pi Imager may also be used, however this step-by-step guide only covers Balena Etcher).
  2. Download an image file from the download section on the Batocera website that matches the architecture you want to use for Batocera (x86_64 for most PCs, other devices usually have their own specific image).

    Some browsers like Chrome/Opera/Safari may take the liberty to unzip the file by themselves and poorly rename them. If the file is more than 3 GB, it is already unzipped. If your download fails, use another browser. Yes, Chrome sucks, that's a fact, use another browser.

  3. Install and run Etcher (or Raspberry Pi Imager if using that).
  4. Insert the intended USB drive, SD card or hard-drive into your computer. 8 GB is the minimum for v30 and up, 16 GB and above is recommended for full functionality (you cannot automatically download updates with only 8 GB).
  5. In Etcher, select the image batocera-(version)-(arch)-(date).img.gz that you just downloaded, and then the target drive like on the following screenshot, and click on Flash! You don't even need to unzip the file, Etcher will take care of it. Etcher's interface.
    • In case the flash fails outright, try closing down any unnecessary software such as anti-virus programs or virtual machines.
  6. Etcher may ask for administrator permissions (to unzip the file). Click “Yes”. Upon finishing, check that the image has been successfully flashed and validated.
    • In case verification fails, try unzipping the file and try again.
  7. Once finished, reinsert your USB drive/SD card/hard-drive and check that it contains a boot folder (files differ depending on architectures). The boot partition.
  8. Shut down your computer and insert your USB drive/SD card/hard-drive into the machine you want to boot with Batocera and turn it on.
  9. Ensure your device will boot into the USB drive/SD card/hard-drive by default.
    1. Most single board computers will automatically boot to the appropriate USB drive/SD card if only one is inserted into the system.
    2. If on a recent PC using an x86/x86_64 build, you may need to disable Secure Boot in your BIOS settings.
    3. If on a PC, you may need to enter the boot selection menu with [F10], [F11] or [F12] and select the Batocera drive. UEFI is preferred if available, but not necessary. Here my Batocera USB stick simply appears as "Generic STORAGE DEVICE"
  10. Boot the Batocera drive and let it automatically expand the partitions (could take a few seconds or a few minutes, depending on your drive size/speed), it will reboot again once done. Don't turn off the device during this step or you might risk data corruption!
  11. Enjoy! =) Of course, your installation is probably in English.

Be sure to check out how to add game ROMs/BIOS files required for certain emulators. Batocera's front-end is driven by a modified version of EmulationStation (sometimes referred to as ES). Check out its overview page to learn how to navigate it!

If your Nvidia GPU is not detected, you may want to manually activate the official drivers for it to increase its performance, but Batocera can run fine using the default nouvaeu drivers if that isn't working for your machine.

Before troubleshooting, check if Batocera has actually booted first! Batocera has booted if:

  • The Batocera splash image appears on any connected display.
  • The SSH server is live and it is possible to log into it.

If this is the case and you only see a blank screen, it is instead a display issue.

Batocera should boot fine with UEFI, if that option appears you should select that. However, sometimes Legacy (or MBR as it's sometimes referred to) is the only option, depending on the motherboard.

Since there's no consistency between motherboard manufacturers, no step-by-step instructions can be provided. You can refer to University of Wisconsin Division of Information Technology's knowledge base page for your particular manufacturer's board on how to enter the BIOS settings on various motherboards during boot. Typical keys are [F12], [F11], [F10], [Del] or [End]. Typical keys for entering the boot selection screen are [F12], [F11], [F10], [F9] or [Del]. Some keyboards may require holding down the [Fn] key too. The manual that came with your motherboard can provide further clues, or you can try exploring all the sub-menus of the BIOS yourself.

To access the BIOS settings from Windows, hold the [Shift] key while selecting Restart and go to Troubleshoot > Advanced Options: UEFI Firmware Settings. Alternatively, go to Settings > Change PC settings > Update and Recovery > Recovery > Advanced Startup: Restart now, and then upon restarting go to Troubleshoot > Advanced Options: UEFI Firmware Settings.

Here are other known aliases BIOS's may use for various settings and what they may need to be set to:

  • Secure boot a.k.a. secure keys, clear keys, secure key generation, ownership, UEFI with CSM, etc. Typically in the “security” category, but can also appear in the “boot” or “authentication” category. You may need to disable secure boot/clear keys, regenerate keys and/or enable the compatibility support module (CSM) to allow other operating systems (such as Batocera) to boot.
  • Legacy boot a.k.a. allow legacy ROM booting, EFI, MBR, load legacy options, show insecure targets, etc. Typically in the “boot settings” category, but sometimes also has its own section. Some motherboards will force any UEFI boots to use Secure Boot with the keys for the original operating system, blocking other operating systems (such as Batocera) from booting. If this is the case for your motherboard, a typical workaround is to use/force Legacy Boot. If neither of these options work, refer to the manufacturer of your motherboard for support.
  • Removable Media Boot a.k.a. USB boot. Typically in the “device”, “storage” or “boot” category. Some motherboards may actively block the booting off of removable media such as USBs. This feature is typically found on office-oriented PCs.
  • Boot order a.k.a. boot priority, ROM order, boot options order, UEFI Hard Disk Drive BBS Priorities, etc. Typically in the “boot” category, but sometimes also has its own section. Some motherboards may treat UEFI as one entry in boot selection, so you'll need to go to the specific UEFI BBS Priorities menu in the BIOS settings to switch the order to your Batocera drive first. In other cases it's not strictly required, but can make the Batocera drive the 'default' booting option when plugged in; ie. you won't have to manually select the Batocera drive to boot off it of every time.

If you'd like to see a real-world example, check out this external link: https://www.tenforums.com/tutorials/85279-enable-disable-secure-boot-windows-10-pc.html

If attempting to run Batocera on a computer that ordinarily runs Windows, you may have to also disable these settings:

  • Fast boot a.k.a. quick boot, quick resume, hybrid sleep, etc. Typically in its own “Windows” category.
  • Windows 8/8.1/10/11 compatibility a.k.a. CSM (note no UEFI, yeah), compatibility mode, legacy support (for older systems), etc. Typically in its own “Windows” category. This should be disabled for alternative operating systems, though turning this off will mean you'll probably have to switch Windows itself to support legacy booting (should do so automatically).
  • TPM a.k.a. Windows 11 compatibility (yeah), TPM Security Module 2.0, USB security, etc. Typically in “security” category. This is a modern “feature” that can prevent alternative operating systems from booting up. All computers with Windows 11 preinstalled going forward will have this activated by default. Turning this off will likely render Windows 11 and above unbootable until it is switched back on, as it is a “system requirement”.

Laptops typically have more restrictions on what they will load compared to tower PC motherboards. Google is your friend here.

If all else fails, refer to the boot section on the troubleshooting page for more things to try and console output.

To access the boot selection screen on Mac, hold the [Option] ([Alt] on ASCII keyboards) key while booting. On newer UEFI Macs, you may first need to turn Secure Boot to “No Security” and enable “Allow booting from external media” from the recovery mode (accessed by pressing and holding [CMD] ([Win] on ASCII keyboards)+[R] immediately after you see the Apple logo while booting).

Some keyboards may require you to hold the [Fn] key as well!

mac-boot1.jpg

If you hold down the [Ctrl] key on this screen, the arrow will change to a circular one;

mac-boot2.jpg

This indicates that your machine will default to booting from this device. Hold [Ctrl]+[Return] ([Enter] on ASCII keyboards) to confirm.

Perhaps you'd like to spread the love and install Batocera onto a machine from an already set-up USB stick? Or maybe you just want to install Batocera directly to your hard-drive. Or maybe you want to prank someone. This is for that.

When Batocera is installed onto your computer's internal hard-drive this way, all existing data (including your currently functional operating system) will be overwritten. There is a chance your motherboard may not be able to boot Batocera from the internal drive, in comparison to booting from USB. Have an additional computer on-hand to be able to recover in case this process fails.

If you would simply like to use your large hard-drive to store all of your ROMs/BIOS's/saves, refer to using external storage instead.

This method is identical to flashing the Batocera image using Etcher. If you have the expertise and tools required, you should instead connect your drive directly to a running computer and flash Batocera using Etcher, so as to save downloading the image from the servers again. The instructions below are for if you cannot do that.

Batocera does not install itself by copying system files over from the USB/SD card like other live distros might. It has to download, extract and install the image as a whole.

  1. Make sure you are connected to the internet and that your USB stick has enough free storage to download the Batocera image.
  2. Boot into Batocera and press [START] to open the MAIN MENU. The Main Menu.
  3. Navigate to SYSTEM SETTINGSINSTALL BATOCERA ON A NEW DISK.
  4. Select the destination you'd like to install Batocera onto. Make sure it's not the same drive you're currently booted off of, as that will corrupt your USB stick!
  5. Check that you've selected the right drive. This is very easy to mess up and its actions are irreversible.
  6. Take a deep breath and check a third time. This is really important.
  7. Select your target architecture. It should be the same as what you selected on the download page when you first installed to your USB (most of the time, this will be X86_64).
  8. Make sure that you're sure about this. Your menu should look similar to this:
  9. Press INSTALL.

Depending on your internet connection, it may take a while to download and install. You cannot use your Batocera system while this is happening.

If you need to install a specific version of Batocera onto your internal drive, and you have no way of just plugging that drive into another computer to flash the version you want onto it, you can always install the latest Batocera and manually downgrade.

Welp you were warned. A few things you can try:

If you're still having trouble, ensure you've also tried the above troubleshooting section or the boot section on the troubleshooting page. If it still fails, revert to booting from USB.

It's actually not possible for Etcher or any flashing tool to do that. However it could be that the drive itself was dying and in the attempt of writing data to it one of its cells started to fail (time for a replacement). Refer to Etcher's article on the topic for more information, and how to possibly “save” a drive. These methods can also be used to “be able to use my USB again” after flashing Batocera.

In essence, on Windows run the following from the command prompt (where # is the number of the desired disk):

diskpart
list disk
select disk #
clean
create partition primary
select partition 1
format quick
  • install_batocera.txt
  • Last modified: 8 days ago
  • by atari