Abdessamad Derraz
0ffde1bc8f
The Batocera example is dated and carries the Not installable line and the closing list of files the collection does not hold, which every Batocera run prints. Disk sizes are no longer hand-kept: the run prints its size. The no-platform case describes the menu install.sh makes possible by handing over the terminal.
8.4 KiB
First install
One path, from an empty BIOS folder to files the emulator can read. Every step shows what the screen looks like when it worked.
If something on this page does not match what happens, the last section covers the cases that come up.
Before starting
Three things, and a few minutes:
- The BIOS folder the emulator reads. The installer finds it by itself on most systems. On a handheld, that usually means plugging the SD card into a computer.
curlorwget, and Python 3.8 or newer. The command below checks for both and stops with a message if either is absent.- Room on the drive. The size depends on the platform and changes with each release: the run prints it before downloading (Step 3), and asks first when it reaches 1 GB. The installer also measures the free space and refuses before writing anything if there is not enough.
Nothing is written outside the BIOS folder, and games and saves are never touched.
Step 1. Run the command
On Linux, macOS, a Steam Deck, or a handheld running Batocera, Recalbox, KNULLI, ROCKNIX or Lakka:
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh
On Windows, in PowerShell:
irm https://raw.githubusercontent.com/Abdess/retrobios/main/install.ps1 | iex
PowerShell's execution policy does not block that line. The policy governs script files, and this command never writes one. Changing the policy is not part of installing anything here.
On Android, from Termux, three commands instead of one:
pkg install python
termux-setup-storage
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh
Before running anything, that first line downloads the installer, compares it against the SHA-256 written inside the command's own script, and refuses to continue if the two differ. To read the script first:
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | less
Step 2. Watch it find the platform
The first lines name what it found and where it will write:
RetroBIOS 8c0e9c762d2f
Detecting platform...
Found Batocera at /userdata/bios
The code after RetroBIOS identifies the installer: it is the start of the SHA-256 the command checked before running it.
That path is the one thing worth reading twice. If it is not where the emulator keeps its BIOS files, stop with Ctrl+C and see the last section.
Step 3. Let it work
The examples on this page follow the Batocera list as published on 2026-10-21. The figures change with each release.
Two phases follow. The first reads what is already in the folder, which takes a few minutes on a memory card because every file is hashed:
Fetching file index for batocera...
14481 files (9.1 GB)
Not installable: 399 files (79 required, not found: 399).
Checking existing files...
0/14481 present (0 verified, 0 wrong hash)
Not installable counts the files of the list that the collection does not
hold. They are named at the end of the run (Step 4).
On a first install the present count is zero, which is expected, not a fault.
On a later run it counts what is already there, and only the rest is
downloaded. A download of 1 GB or more is confirmed first
(Download 9.1 GB to /userdata/bios? [Y/n]).
The second phase downloads what is missing, one line per file:
Downloading 14481 files (9.1 GB)...
Press Ctrl+C to stop. Running the same command again carries on from here.
[1/14481] 3do_arcade_saot.bin ok
[2/14481] 3dobios.zip ok
Ctrl+C is safe at any point. Files already installed stay, and running the command again picks up where it stopped.
Step 4. Read the end of the run
This is what a finished run looks like:
Done. 14481 files installed, 0 files already up to date.
Location: /userdata/bios
399 files were not installed: the collection does not hold them, or its copy fails their check.
Needed to start an emulator (79 files):
dark-forces (theforceengine): DARK.GOB, SOUNDS.GOB, SPRITES.GOB, TEXTURES.GOB
dark-forces-ii (openjkdf2): openjkdf2/episode/JK1.gob, openjkdf2/episode/JK1CTF.gob, openjkdf2/episode/JK1MP.gob, openjkdf2/resource/Res1hi.gob, openjkdf2/resource/Res2.gob
diablo (devilutionx): devilutionx/diabdat.mpq
doom3 (dhewm3): base/pak000.pk4, base/pak002.pk4, base/pak003.pk4, base/pak004.pk4
droidworks (openjkdf2): dwCD.GOB, dwHD.GOB, dwMin.GOB, dwStream.GOB
fallout (fallout1-ce): fallout1-ce/critter.dat, fallout1-ce/master.dat
fallout2 (fallout2-ce): fallout2-ce/critter.dat, fallout2-ce/master.dat
fury (fury): fury.grp
... and 9 more systems (--check --verbose lists them all)
Each emulator's page says what these files are: https://abdess.github.io/retrobios/emulators/
To check this later, run the same command with --check.
The word Done and a location are the confirmation. Any other ending (Stopped,
Finished with errors, Nothing was installed) means something was left undone,
and the run says which case it was.
The lines between Location: and the --check hint name the files of the list
that the collection does not hold. Needed to start an emulator gives, for each
system, the emulators that read it and the files they cannot start without. On
the run above, all 79 belong to games (Dark Forces, Diablo, Doom 3, Tomb Raider
and the others): the engine reads them from a copy of the game itself. The
other 320 are optional, and the emulators reading them start without them.
Step 5. Confirm it later
The same command with --check reads the folder and writes nothing:
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --check
Checking existing files...
14481/14481 present (14481 verified, 0 wrong hash)
All files up to date.
The files the collection does not hold are listed after it again, as long as
they are absent from the folder. 0 wrong hash is the line that matters. A number there means a file is present
whose contents the platform will reject, and running the install again replaces
it.
When the screen says something else
No supported platform detected.
At a terminal, a menu follows that line. The platform is picked by its number, then the run asks for the BIOS folder, offering the platform's usual folder on this system as the default when it has one.
Without a terminal, or with --no-input, the run stops there and prints the
command to use instead, with the platform and the folder named:
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh \
| sh -s -- --platform retroarch --dest /path/to/system
The accepted names come from --list-platforms. For where each platform keeps
its BIOS folder, see Getting started.
Error: Python 3.8 or newer is required.
No Python 3.8 or newer was found: Python is missing, or older. The message
names the command that installs it, sudo apt install python3 on Debian and
Ubuntu. On a handheld running Batocera or Recalbox it is already there, so
this message usually means the command ran on the computer rather than on the
console.
A stock RetroPie 4.8 image is Debian Buster, where python3 is 3.7.3 and apt
has nothing newer, so the same command changes nothing. The RetroPie pack from
the releases page,
extracted into ~/RetroPie/BIOS/, installs the same files.
Error: the downloaded installer does not match its expected fingerprint.
Nothing was run and nothing was written. The download did not match the fingerprint the script carries, which is almost always a transfer cut short. Running the command again, on another network if possible, is the answer.
Cannot create ...
The user running the command cannot write there. On Batocera, Recalbox and
ROCKNIX the BIOS folder belongs to root, so the same command with sudo in
front of it succeeds.
Not enough space on the drive holding ...
The run stopped before writing. The message names how much is needed and how
much is free. --dest installs to another drive.
The game still shows a black screen
A file can be in place and still be the wrong one for that game, or the console may need a file that nobody has dumped yet. Troubleshooting goes through that case.
What comes next
- Troubleshooting, when a game does not start
- FAQ, for what the words mean and why a pack is this large
- Installer, for every option, what it detects and what it is allowed to write