libretro/wiki/getting-started.md

# Getting started

## What are BIOS files?

BIOS files are firmware dumps from original console hardware. Emulators need them to boot games for systems that relied on built-in software (PlayStation, Saturn, Dreamcast, etc.). Without the correct BIOS, the emulator either refuses to start the game or falls back to less accurate software emulation.

## Installation

Three ways to get BIOS files in place. The installer is the one to use,
and the two sections after it are for when it cannot run. For a walkthrough of a
first install with what each step prints, see
[First install](first-install.md).

### Option 1: the installer (recommended)

One command, nothing to clone. The bootstrap verifies `install.py` against the
SHA-256 embedded in it, then the installer detects the platform and its BIOS
directory, downloads only what is missing or incorrect, checks size and
SHA-256/SHA-1 before writing, and installs each file atomically.

```bash
# Linux / macOS / Steam Deck
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/Abdess/retrobios/main/install.ps1 | iex

# Android, from Termux, after pkg install python and termux-setup-storage
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh
```

Running `install.py` directly works the same way and needs nothing beyond
Python 3.8+, the floor both bootstraps enforce before they hand over:

```bash
python install.py
```

Override detection when needed:

```bash
python install.py --platform retroarch --dest ~/custom/bios
python install.py --target switch      # keep only files for that hardware
python install.py --list-systems       # systems a platform holds, with sizes
python install.py --system sony-playstation,nintendo-gba
python install.py --region us,eu,jp    # one BIOS per region, best first
python install.py --no-input           # ask nothing, even at a terminal
python install.py --check              # verify existing files, download nothing
python install.py --list-platforms     # supported platforms and what was detected
python install.py --list-targets       # hardware targets for a platform
python install.py --jobs 4             # parallel downloads (default 8)
python install.py --verbose
python install.py --standalone-copies  # opt in to extra standalone-emulator paths
```

The default flow writes inside the detected platform tree only. Copies into
separate standalone-emulator directories are opt-in, so discovery cannot cause
unexpected writes elsewhere on the machine. Entries the collection cannot
satisfy are reported as safely omitted and the run continues. The installer
never substitutes a same-named file for one a hash-verifying platform would
reject.

Arguments pass through the one-liner too, which is how you target an SD card
mounted on another machine:

```bash
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh \
  | sh -s -- --platform retroarch --dest /path/to/sdcard/retroarch/cores/system
```

`--dest` is the BIOS folder itself, so on a card it names that folder on the
card: `retroarch/cores/system` for RetroArch on Switch, `RetroArch/system` on
Android.

PowerShell needs another form, the environment overrides and the detection
rules are listed per platform, and the trust boundary is described in full on
the [Installer](installer.md) page.

### Option 2: download.sh (Linux/macOS, from a clone)

Downloads a whole pack rather than the missing files. Needs `curl` and `unzip`:

```bash
bash scripts/download.sh retroarch ~/RetroArch/system/
bash scripts/download.sh --list  # show available packs
```

A pack published in several parts is downloaded part by part and checked
against the SHA-256 the release publishes before anything is extracted.
`python scripts/download.py` does the same on Windows.

### Option 3: manual download

1. Go to the [releases page](https://github.com/Abdess/retrobios/releases)
2. Download the ZIP pack for your platform
3. Extract to the BIOS directory listed below

A pack over 2 GB comes in several parts (`Pack.part1of2.zip`,
`Pack.part2of2.zip`), and every part is needed. Each part is an ordinary ZIP:
extract them all into the same folder. See [Download](../which-pack.md) for
the per-setup instructions.

## BIOS directory by platform

### RetroArch

RetroArch uses the `system_directory` setting in `retroarch.cfg`. Default locations:

| OS | Default path |
|----|-------------|
| Windows (installer or portable .7z) | `system\` next to `retroarch.exe` |
| Windows (UWP/MSIX package) | `%LOCALAPPDATA%\Packages\1e4cf179-f3c2-404f-b9f3-cb2070a5aad8_*\LocalState\system\` |
| Linux | `~/.config/retroarch/system/` |
| Linux (Flatpak) | `~/.var/app/org.libretro.RetroArch/config/retroarch/system/` |
| macOS | `~/Library/Application Support/RetroArch/system/` |
| Steam Deck (Flatpak) | `~/.var/app/org.libretro.RetroArch/config/retroarch/system/` |
| Android | `/storage/emulated/0/RetroArch/system/` |

On Windows, `retroarch.cfg` is read beside `retroarch.exe` first, then from
`%APPDATA%\RetroArch\`. Either way, a `system_directory` left at its default is
the `system` folder beside `retroarch.exe` (`:\system` in RetroArch's
`frontend/drivers/platform_win32.c`, where `:` stands for the folder of the
executable).

To check your actual path: open RetroArch, go to **Settings > Directory > System/BIOS**, or look for `system_directory` in `retroarch.cfg`.

### Batocera

```
/userdata/bios/
```

Accessible via network share at `\\BATOCERA\share\bios\` (Windows) or `smb://batocera/share/bios/` (macOS/Linux).

### Recalbox

```
/recalbox/share/bios/
```

Accessible via network share at `\\RECALBOX\share\bios\`.

### RetroBat

```
bios/
```

Relative to the RetroBat installation directory (e.g., `C:\RetroBat\bios\`).

### RetroDECK

```
~/retrodeck/bios/
```

On a MicroSD install the root moves, e.g. `/run/media/mmcblk0p1/retrodeck/bios/`.

The RetroDECK pack is the exception to "extract into the BIOS directory": its
entries already start with `bios/` (and one with `roms/`), so extract it into
`~/retrodeck/` and the files land in the right place. Extracting into
`~/retrodeck/bios/` would create `~/retrodeck/bios/bios/`.

### EmuDeck

```
Emulation/bios/
```

Located inside your Emulation folder. On Steam Deck, typically `~/Emulation/bios/`.

### Lakka

```
/storage/system/
```

Accessible via SSH or Samba.

### RetroPie

```
~/RetroPie/BIOS/
```

RetroPie is archived in this project: its configuration is kept and packs are
still built, but the upstream data is no longer scraped on a schedule. Use the
RetroPie pack, not the RetroArch one: RetroPie inherits RetroArch's systems
but also installs standalone emulators (openMSX, PCSX2, XRoar, Amiberry and
others) whose files only the RetroPie pack carries, laid out for
`~/RetroPie/BIOS/` rather than RetroArch's `system/`.

### ROCKNIX

```
/storage/roms/bios/
```

Accessible via SSH or Samba, like Lakka.

### KNULLI

```
/userdata/bios/
```

### AmberELEC and EmuELEC

```
/storage/roms/
```

Their BIOS lists name files under `/storage/roms`: `bios/` for most, and
`neogeo/` (and `ports/` on EmuELEC) for the rest. The pack holds those
folders, so it is extracted into `/storage/roms/` itself.

### MiSTer FPGA

```
/media/fat/games/
```

Files go under the per-core subdirectory the MiSTer BIOS database declares
(e.g. `/media/fat/games/3DO/boot.rom`). Only the entries the BIOS database
lists with a download URL are in scope: the rest ship with the MiSTer
distribution and install themselves.

### MinUI, NextUI and MyMinUI

```
<SD card>/Bios/<TAG>/
```

These frontends give each core a folder of its own, named after the tag in
parentheses of the Roms folder the game sits in: a game in
`Roms/Sony PlayStation (PS)/` runs with `Bios/PS/` as its system directory, one
in `Roms/Game Boy (GB)/` with `Bios/GB/` (MinUI
`workspace/all/minarch/minarch.c:2943`, NextUI
`workspace/all/minarch/ma_core.c:76`, MyMinUI
`workspace/all/minarch/minarch.c:3532`). The pack holds the `Bios/` folder:
extract it at the root of the card. A core started from two tags (Gambatte for
GB and GBC) gets its files in both folders.

The installer runs on the computer the card is mounted on, with the card's root
as `--dest`:

```bash
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --platform minui --dest /media/$USER/CARD
```

Without `--platform`, it reads the release name the frontend writes in
`.system/version.txt` on the card. A pak that starts a standalone program
instead of a libretro core (DraStic for NDS, native PICO-8) is not covered.

### BizHawk

```
Firmware/
```

Relative to the BizHawk installation directory.

### RomM

BIOS files live in the RomM library under `bios/{platform_slug}/`, one
subfolder per system, and are managed through the web interface. Check the
[RomM documentation](https://github.com/rommapp/romm) for setup details.

## Checking what you installed

`--check` reads the BIOS folder, hashes what is there and writes nothing:

```bash
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --check
```

It ends on a count:

```
Checking existing files...
  5865/5865 present (5865 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, which is how a wrong revision or a bad
dump shows up.

The installer's `--check` hashes every file against the list on every
platform, so it catches a wrong revision even where the frontend would not:
RetroArch, Lakka, RetroPie, MinUI, NextUI and MyMinUI only check that a file
exists, while Batocera, RetroBat, Recalbox, EmuDeck, RetroDECK, RomM, ROCKNIX,
KNULLI, AmberELEC, EmuELEC and MiSTer FPGA compare
MD5 and BizHawk compares SHA1.

For a single system, or the files a single emulator core reads (`--list-systems`
and `--list-cores` give the names):

```bash
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --check --system sony-playstation
curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --check --emulator beetle_psx
```

`--verbose` names every file still to fetch, wrong hashes included. See [Installer](installer.md)
for every option, and [Tools](tools.md) for the repository's own scripts.

## Next steps

- [FAQ](faq.md) - common questions and troubleshooting
- [Tools](tools.md) - all available scripts and options
- [Architecture](architecture.md) - how the project works internally