5.6 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, so there is never a moment of wondering.
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. A full RetroArch set is 5.5 GB, Batocera 4.0 GB, MiSTer FPGA 24 MB. The installer 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
Detecting platform...
Found Batocera at /userdata/bios
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
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 misterfpga...
72 files (24.0 MB)
Checking existing files...
72/72 present (72 verified, 0 wrong hash)
On a first install those numbers are zeros, which is expected, not a fault.
The second phase downloads what is missing, one line per file:
Downloading 72 files (24.0 MB)...
Press Ctrl+C to stop. Running the same command again carries on from here.
[1/72] AtariLynx/boot.rom ok
[2/72] Astrocade/boot.rom 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 last three lines
This is what a finished run looks like:
Done. 72 files installed, 0 files already up to date.
Location: /userdata/bios
To check this later, run the same command with --check.
The word Done and a location are the confirmation. Any other ending means
something was left undone, and the run says which case it was.
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...
72/72 present (72 verified, 0 wrong hash)
All files up to date.
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.
The command was piped from the internet, so it cannot stop and ask a question. Name the platform and the folder instead:
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.
Python is missing from the machine. On Debian and Ubuntu, sudo apt install python3; 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.
Error: install.py SHA-256 mismatch.
Nothing was run. The download did not match the fingerprint the script expects, which is almost always a truncated or intercepted transfer. 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