# Raspberry Pi 5 image: concrete build investigation

Research checked 2026-09-26 UTC. **No Pi 5 disk image has been built, downloaded in full, flashed, booted or physically tested by this project.** These are source observations and a proposed experiment plan.

## Existing upstream work changes the starting point

The main [RetroPie download page](https://retropie.org.uk/download/) and latest tagged GitHub release expose 4.8 Buster images through Pi 4/400. The separate [weekly image directory](https://files.retropie.org.uk/images/weekly/) includes Pi 5 builds. Its [README](https://files.retropie.org.uk/images/weekly/README.txt) labels them automated development builds without testing or support, separate from official supported releases.

The directory contained Bookworm 4.8.12 images dated 2026-08-25, including 32-bit and 64-bit Pi 5 variants. Therefore, “there is no upstream Pi 5 image” would be inaccurate. The opportunity is tested releases, a documented maintenance process and useful independent support.

The [64-bit Pi 5 image](https://files.retropie.org.uk/images/weekly/retropie-bookworm-64-4.8.12-rpi5.img.xz) has [published metadata](https://files.retropie.org.uk/images/weekly/retropie-bookworm-64-4.8.12-rpi5.img.json) describing:

| Field | Observed value |
| --- | --- |
| Compressed bytes | 881,463,784 |
| Extracted bytes | 4,120,903,680 |
| Extracted SHA-256 | `5df55bf53cfada6c40cd102ed9cf65eed9d109f051c7a67578e659d0034b792d` |
| OS | Bookworm, 64-bit |
| Declared upstream status | Development, untested, unsupported |

The hash is for the **extracted `.img`**, not the downloaded `.xz`. Metadata contains a GitHub download URL different from the working weekly listing; verify the actual endpoint and file before use. Save the complete compressed file, calculate its own SHA-256, check decompression and extracted size/hash, and preserve the metadata with the experiment. Filename/version alone does not identify the exact setup commit used in that historical build. `src/data/pi5-weekly.json` records the inspected metadata, not a verified artifact.

## First builder to investigate: RetroPie's own

At [RetroPie-Setup revision 664d2537d310edea267994097f800f82387f1a5d](https://github.com/RetroPie/RetroPie-Setup/tree/664d2537d310edea267994097f800f82387f1a5d), the [image administration module](https://github.com/RetroPie/RetroPie-Setup/blob/664d2537d310edea267994097f800f82387f1a5d/scriptmodules/admin/image.sh) creates a chroot from a distribution image, installs the selected platform, creates a bootable image and compresses it with xz. It also generates Raspberry Pi Imager metadata using the extracted image hash.

Its [64-bit Bookworm distribution configuration](https://github.com/RetroPie/RetroPie-Setup/blob/664d2537d310edea267994097f800f82387f1a5d/scriptmodules/admin/image/dists/rpios-bookworm-64.ini) explicitly lists `rpi3 rpi4 rpi5`. It references the 2026-04-13 Bookworm ARM64 Lite base image. This differs from the newer base currently offered on Raspberry Pi's download page; record that difference rather than silently substituting a base while trying to reproduce upstream behavior.

The module's platform function takes `platform`, `dist`, and an optional Berryboot flag. The prospective invocation to validate on a **disposable Linux build host**, after reviewing the entry point and prerequisites, is:

```sh
# Research candidate, NOT an executed or tested recipe.
# Requires root and modifies chroot, loop-device and host binfmt state.
sudo ./retropie_packages.sh image platform rpi5 rpios-bookworm-64
```

Dependency inspection shows partition/filesystem tools, kpartx, rsync and binfmt; x86 hosts additionally use QEMU user emulation. That can help with image assembly but does not validate Pi GPU, audio, input or runtime performance. Do not run these host-mutating operations directly on the Mac or the website EC2 instance. Use a purpose-built Linux VM or ARM64 builder with enough disk for base, chroot, build workspaces and multiple image copies. Start by measuring real resource use; reserve tens of GB of disposable storage and revise from observed logs.

The pinned distribution directory includes Bookworm but no Trixie configuration. Trixie therefore requires an explicit new build configuration and compatibility work; it is not an already-proven option in this builder. Prefer reproducing the Bookworm baseline first, then evaluate current Trixie on a separate branch/card. This refines the earlier general recommendation to start immediately on Trixie.

### Concrete changes required before an independent release

The inspected `install_rp_image` script defaults its internal clone to `master` (`__chroot_branch`) even when the outer checkout is pinned. It also sets the shared `pi:raspberry` password and disables `userconfig` when that service is enabled. Its generated module loop does not itself implement a per-module release gate. These are observed implementation details, not hypothetical risks. Pin and verify the inner clone, replace shared-login setup with tested first-boot provisioning, and collect/gate every module result before using this builder for a public independent release. Do not assume the candidate command above already satisfies these requirements.

## Alternative builder

[Raspberry Pi rpi-image-gen](https://github.com/raspberrypi/rpi-image-gen) is an official framework for customized images. Evaluate it if the upstream builder cannot meet first-boot, package pinning or maintenance requirements. It would need a RetroPie installation layer and the same hardware tests. A new build framework is unnecessary until there is evidence the existing path is inadequate.

## Experiments in order

1. **Observe the board.** Record Pi 5 RAM, PSU, cooling, storage, attached display and wired controller. Keep the owner's current card intact; use a spare test card later.
2. **Evaluate the upstream weekly candidate.** Verify bytes and hashes, inspect image partitions/configuration before boot, then run the minimum hardware matrix. Record every change needed. Treat this as comparison evidence, not our release.
3. **Install manually on clean Bookworm Lite ARM64.** Record exact base hash and a pinned setup revision. Begin with EmulationStation, RetroArch and one rights-cleared test program. Record module results instead of treating setup-script completion as overall success.
4. **Rebuild with upstream image tooling.** Capture prerequisites, command arguments, package versions, source commits, logs and outputs. Recreate the manual baseline in a clean builder.
5. **Compare the three paths.** Identify problems specific to base age, current upstream setup, image configuration, graphics or the selected module. Keep patches narrowly documented and propose useful fixes upstream.
6. **Evaluate Trixie.** Use the same physical test matrix. Choose the maintained release base from observed results and update needs, not from its name alone.

## Pi 5-specific questions

- Graphics: KMS/Mesa, SDL backend, EmulationStation launch mode and return-to-menu behavior. The setup platform already recognizes Cortex-A76; that alone proves no emulator works.
- Kernel/architecture: check selected kernel, page size and 64-bit userland assumptions. The image script selects a 4 KiB kernel for 64-bit builds; preserve and investigate that choice before changing it.
- Audio: HDMI selection, volume, reconnect and emulator-to-menu transitions. Treat USB/Bluetooth audio as later independent coverage.
- Input: wired controller mapping, hotkeys, hotplug and player order; investigate Bluetooth separately.
- Thermal/power: stock clocks, known PSU/cooling, sustained load and throttling observations.
- Storage/accessories: microSD first. GPIO arcade boards, NVMe and alternate display configurations require independent checks.
- Maintenance: binary availability for each OS/architecture, source-build failures, package updates, safe recovery and rollback.

## Minimum release evidence and artifacts

Use the [hardware test plan](07-hardware-test-plan.md) for boot, accounts, display, audio, controller, saves, clean shutdown, sustained play, backup restoration and update recovery. Retain actual observed results and failure logs. No test currently has a physical PASS.

Pin the base, OS packages, RetroPie setup, module sources, toolchain and patches. Some modules fetch moving branches, so a setup commit alone does not make a reproducible build. Start with repeatable behavior; only claim bit-for-bit reproducibility after proving it.

Before publishing an independent alpha, provide first-boot account creation, unique machine identity and host keys, a clean image without builder secrets, a tested package list, component licenses and corresponding source, compressed and extracted hashes, signed manifest, build logs, release notes, flashing/recovery guide and explicit limitations. Do not add commercial ROMs or firmware bundles. Preserve each component's license rather than applying “free use” to the entire image.

The initial release promise should be modest: a working frontend and a deliberately selected small set of systems on a defined Pi 5 configuration. Advanced consoles and unusual hardware should stay outside that promise until separately tested.