Differences

This shows you the differences between two versions of the page.

--- install_batocera [2023/01/20 17:43] – darknior
+++ install_batocera [2026/03/30 13:53] (current) – Fixed file name pattern lbrpdx
@@ Line 12: / Line 12: @@
 Generic instructions for most platforms are as follows:
-  - Download [[https://www.balena.io/etcher/|Balena Etcher]] for your operating system ([[https://www.raspberrypi.com/software/|Raspberry Pi Imager]] may also be used, however this step-by-step guide only covers Balena Etcher).
+  - Download an image flashing tool for your operating system such as [[https://www.raspberrypi.com/software/|Raspberry Pi Imager]] or [[https://gitlab.com/bztsrc/usbimager|USBImager]]. We will be using Raspberry Pi Imager in these instructions. {{ :install_rpi_imager_01.png?direct&640 |}}
   - Download an image file from the [[https://batocera.org/#download|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). <WRAP center round important>
-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.
+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 4 GB, it is already unzipped. If your download fails, use another browser. Yes, Chrome sucks, that's a fact, use another browser.
 </WRAP>
-  - Install and run Etcher (or Raspberry Pi Imager if using that).
+  - Insert the intended USB drive, SD card, hard-drive or SSD (you can attach one via a SATA/M.2 to USB cable) into your computer. 16 GB storage space is the minimum, 32 GB is recommended for full functionality (you cannot automatically download updates with only 16 GB).
-  - 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).
+  - Install and run Raspberry Pi Imager.
-  - 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. {{ etcher1.png?nolink&640 |Etcher's interface.}}
+  - Click **CHOOSE OS**. {{ :install_rpi_imager_02.png?direct&540 |}}
-    * In case the flash fails outright, try closing down any unnecessary software such as anti-virus programs or virtual machines.
+  - Scroll down and select **Use custom**. {{ :install_rpi_imager_03.png?direct&540 |}}
-  - Etcher may ask for administrator permissions (to unzip the file). Click "Yes". Upon finishing, check that the image has been successfully flashed and validated. {{ :etcher-success.png?nolink&640 |}}
+  - Select the image ''batocera-(arch)-(version)-(date).img.gz'' that you just downloaded. {{ :install_rpi_imager_04.png?direct&540 |}}
-    * In case verification fails, try unzipping the file and try again.
+  - Click **CHOOSE STORAGE** and select the USB drive, SD card or hard-drive. {{ :install_rpi_imager_05.png?direct&540 |}} {{ :install_rpi_imager_06.png?direct&540 |}}
-  - Once finished, reinsert your USB drive/SD card/hard-drive and check that it contains a boot folder (files differ depending on architectures). Don't worry that it's only a few gigabytes large, this is just Batocera's boot partition! {{ :boot-partition1.png?nolink&600 |The boot partition.}}
+  - Click **NEXT**. {{ :install_rpi_imager_07.png?direct&540 |}}
-  - 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.
+  - Click **NO**. {{ :install_rpi_imager_07b.png?direct&540 |}}
-  - Ensure your device will boot into the USB drive/SD card/hard-drive by default.
+  - <wrap em>Confirm</wrap> that it is the correct destination (triple-check it's the correct drive before proceeding, as <wrap em>all existing data on the drive will be destroyed!</wrap>), then click **YES**. {{ :install_rpi_imager_07c.png?direct&540 |}}
+  - Wait patiently for the writing to finish, this may take a while depending on the speed of the card/drive. <WRAP center round important>
+Windows may offer to format the drive thinking it is a new device, cancel this request otherwise Batocera will be wiped out.
+</WRAP> {{ :install_rpi_imager_08.png?direct&540 |}}
+    * In case the flash fails outright, try closing down any unnecessary software such as anti-virus programs or virtual machines and try again.
+  - Upon finishing, check that the image has been written successfully. {{ :install_rpi_imager_09.png?direct&540 |}}\\ <WRAP center round tip>
+At this point, the drive contains a ''BATOCERA'' boot partition (files differ depending on architectures). This partition will be smaller than the total size of the drive, don't worry as this is just Batocera's boot partition! {{ :boot-partition1.png?nolink&600 |The boot partition.}} The drive also contains a ''SHARE'' partition which will be expanded the first time the drive is booted, to consume any unallocated space, and which is not normally visible to Windows.
+</WRAP>
+  - Shut down your computer and insert your USB drive, SD card or hard-drive into the machine you want to boot with Batocera and turn it on.
+  - Ensure your device will boot into the USB drive, SD card or hard-drive:
     - Most single board computers will automatically boot to the appropriate USB drive/SD card if only one is inserted into the system.
     - If on a recent PC using an x86/x86_64 build, you may need to [[#bios_settings_(if_batocera_fails_to_boot)|disable Secure Boot in your BIOS settings]].
     - 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. {{ typical-boot-menu.jpg?nolink&323 |Here my Batocera USB stick simply appears as "Generic STORAGE DEVICE"}}
-  - Boot the Batocera drive and let it automatically expand the userdata partition (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! {{ :batocera_resize_partition.jpg?480 |}}
+  - Boot the Batocera drive and let it automatically expand the userdata partition (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! {{ :batocera_resize_partition.jpg?540 |}} <WRAP center round info>
-  - Enjoy! =) {{ https://batocera.org/images/blog/Pictures/Version_29/output001.png?nolink&480 |Of course, your installation is probably in English.}}
+If instead another blue screen appears saying verification failed this means you are in secure boot mode and have not enrolled Batocera's keys yet. Press ''Enter'' and follow the on-screen prompts to do so, for further info refer to the [[:secureboot|the secure boot page]]. {{secure_boot_x64_-_2_-_error_verification_failed_0x1a_security_violation_-_screenshot_2023-10-20_121355.png?w=540}} {{tpm_1_boot_option_restoration.jpg?w=600}}
+</WRAP>
+  - Enjoy! =) {{ https://batocera.org/images/blog/Pictures/Version_29/output001.png?nolink&540 |Of course, your installation is probably in English.}}
 Be sure to check out [[:add_games_bios|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 [[:emulationstation_overview|its overview page]] to learn how to navigate it!
@@ Line 37: / Line 48: @@
 ===== Flash failed! =====
-Don't panic. Etcher will usually explain what went wrong in its error message, so be sure to read that completely. The usual suspect is that the verification failed, meaning that the data read back to Etcher does not match up with the data from the image; time to get a replacement drive.
+Don't panic. the imager will usually explain what went wrong in its error message, so be sure to read that completely.
-If instead Etcher does not state what went wrong, it's likely because of an ancient bug in Windows that prevents it from seeing multiple partitions on any USB drive. This can be fixed easily by reformatting the entire drive to NTFS and then trying again. In case Windows' own tools fail to do this, there are [[#etcher_broke_my_usb|command prompt instructions below]] to forcefully wipe the drive. Yes, this is as dangerous as it sounds.
+If using Balena Etcher to flash Batocera, and it does not state what went wrong, it's likely because of an ancient bug in Windows that prevents it from seeing multiple partitions on any USB drive. This can be fixed easily by reformatting the entire drive to NTFS and then trying again. In case Windows' own tools fail to do this, there are [[#etcher_broke_my_usb|command prompt instructions below]] to forcefully wipe the drive. Yes, this is as dangerous as it sounds.
 ===== BIOS settings (if Batocera fails to boot) =====
@@ Line 55: / Line 66: @@
 Since there's no consistency between motherboard manufacturers, no step-by-step instructions can be provided. You can refer to [[https://kb.wisc.edu/helpdesk/page.php?id=58779|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**.
+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.
+  * **Secure boot** a.k.a. compatibility mode, compatibility support module, 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.
+    * **Enroll an EFI** a.k.a. add keys, secure key generation, ownership, etc. //Typically in the "security" category, but can also appear in the "boot" or "authentication" category.// Most motherboards should automatically add detected EFIs to the list of permitted bootable drives, but certain motherboards require this to be a manual action. Add the file at ''EFI/boot/bootx64.efi'' from the Batocera boot drive. This can be avoided entirely by switching secure boot off.
   * **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.
@@ Line 77: / Line 89: @@
 ===== Mac boot order selection =====
-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).
+=== Before booting: Disable Secure Boot and enable booting from external media (On Newer UEFI Macs) ===
+  * Reboot your MAC, at Apple logo press and hold ''[CMD]'' (''[Win]'' on ASCII keyboards)+''[R]''
+  * Mac will starts the macOS recovery mode, select and login with your admin account.
+  * At top menu bar, select ''Utilities'' >> ''Startup Security Utility'', and enter you admin account password again.
+  * Changes Secure Boot to ''No Security'' and Allowed Boot Media to ''Allow booting from external or removable mode''.
+  * Close it and Restart your Mac.
+  * Follow instructions on next section...
+==== Startup Batocera ====
+To access the boot selection screen on Mac, hold the ''[Option]'' (''[Alt]'' on ASCII keyboards) key while booting.
 <WRAP center round tip>
@@ Line 91: / Line 114: @@
 This indicates that your machine will default to booting from this device. Hold ''[Ctrl]''+''[Return]'' (''[Enter]'' on ASCII keyboards) to confirm.
-===== Steam Deck boot order selection =====
+<WRAP center round important>
+On Macbooks especially, some hardware such as the touchpad or keyboard may not be supported under Linux. Fortunately, Batocera is functional with a controller alone.
-To access the BIOS (UEFI boot menu) of the Steam Deck, you need to turn it on by holding ''[Volume +]'' and the ''[Power]'' button. As soon as you hear a beep, you release them.
-{{ ::tuto1.png?nolink&400 |}}
-Use the ''[DPad]'' and the ''[A button]'' to go to the **Setup Utility** menu at the bottom right.
-Then, choose the **Boot** section, and the **Add Boot Options" option**.
-{{ :tuto2.png?nolink&600 |}}
-And replace **Auto** by **First**. **First** is the SDCard slot, and the Steam Deck will use it first when booting.
-Finally, go to the **Exit** section and select **Save and Exit** to restart with the changes.
-<WRAP center round tip>
-You must have already installed Batocera on your SD Card, before this tutorial.
 </WRAP>
 ===== Install Batocera from Batocera =====
@@ Line 143: / Line 149: @@
 </WRAP>
-==== Batocera no boot from internal hard-drive! ====
+==== Batocera does not boot from internal drive ====
-Welp you were warned. A few things you can try:
+A few things you can try:
   * Configure your motherboard's BIOS settings to allow loading the ''bootx64.efi'' file. This may involve going into a specific EFI boot-order submenu. As [[#bios_settings_if_batocera_fails_to_boot|above]], every motherboard is unique in this regard.
   * [[:upgrade_manually|Manually install Batocera]] onto an already existing bootable EFI partition.