rpi-eeprom holds the Pi bootloader images, and a bad flash can leave a board unbootable

The bootloader lives in EEPROM, outside the SD card

The rpi-eeprom repository contains the scripts and pre-compiled binaries used to create the rpi-eeprom package, which is used to update the bootloader EEPROM on the supported Raspberry Pi models. The list is Raspberry Pi 4 Model B, Raspberry Pi 400, Compute Module 4, Compute Module 4S, Raspberry Pi 5, Raspberry Pi 500, Raspberry Pi 500+ and Compute Module 5.

The layout of the images follows the two SoC families. The firmware-2711 directory contains the EEPROM images for BCM2711-based products, which are the Pi 4, the 400, the CM4 and the CM4S, and firmware-2712 contains the images for BCM2712-based products, which are the Pi 5, the 500 and the CM5.

That split is the whole reason the repository is structured this way. The bootloader is not code on the SD card, it is code in a chip soldered to the board, and the image that runs depends on which SoC revision the board has. Putting the wrong family's image on a board is the kind of mistake this layout is designed to prevent.

The consequence for an owner is that a board can end up unable to boot for reasons that have nothing to do with the operating system. The README is explicit that a newer board may depend on bootloader fixes for hardware that did not exist when older EEPROM releases were built, for example new SDRAM part numbers, revised power-supply sequencing or PMIC behaviour, and that installing an EEPROM image that pre-dates the board can leave it unable to boot reliably, or at all.

The staged update is the default, and it is the safe path

The end-user tool is rpi-eeprom-update, and it is run by the rpi-eeprom-update systemd service on Raspberry Pi OS.

The default mechanism is deliberately indirect. The tool compares the currently installed EEPROM version against the selected release, default or latest and the others in firmware-2711 and firmware-2712, and if the release is newer it stages the image so that it is flashed at the next reboot by recovery.bin, or by self-update on BCM2711.

Staging rather than writing is the point. The image is written to the boot partition while the system is running normally, and the actual EEPROM rewrite happens during the next boot, in a context where the board is not doing anything else. If power is lost during that rewrite there is a real risk, which is why the alternative exists at all.

The tool can also install an arbitrary image with rpi-eeprom-update -d -f pieeprom.bin, which is the path for a custom build.

The repository layout confirms the tool structure. There are rpi-eeprom-update, rpi-eeprom-config, rpi-eeprom-digest, rpi-eeprom-update-default, the rpi-bootloader-version file, the imager/ directory, the firmware-2711 and firmware-2712 directories, a test/ directory, a tools/ directory and releases.md.

The other scripts in the repository are building blocks for preparing a custom or signed EEPROM image, typically driven from update-pieeprom.sh in the separate usbboot repository, so the end user normally touches only rpi-eeprom-update.

Immediate updates are a flashrom write, and the warning is literal

Setting RPI_EEPROM_IMMEDIATE_UPDATE=1 in /etc/default/rpi-eeprom-update makes the tool write the EEPROM while the system is running, rather than staging for the next reboot.

There are two mechanisms for that. rpi-eeprom-ab is used on BCM2712 boards that already have AB EEPROM enabled, and needs no extra setup beyond the environment variable. flashrom is used on all other boards, requires the flashrom package to be installed, and rpi-eeprom-update will fall back to the staged update if flashrom is not on PATH.

The README's warning is short and absolute: power must not be lost during a flashrom update. If it is, the EEPROM must be re-flashed using the Raspberry Pi Imager bootloader-restore feature.

That is a hardware-level failure mode with a hardware-level recovery, and it is the reason the staged path is the default. A staged update survives a power cut because the write happens in the boot sequence with nothing else running. An immediate update does not, because the write happens while your services are up.

Before an immediate update the tool probes the SPI flash with flashrom -p linux_spi:dev=<spidev>, and aborts back to a staged update if the probe fails, or reports Unknown flash chip. Generic SFDP handling of unknown flash chips is not supported because SFDP data cannot always be trusted.

On Raspberry Pi OS, a patched downstream flashrom 1.4 is shipped with definitions for all the different chips a Raspberry Pi could be manufactured with. If you run the tool on another distribution, you either need that patched build or a flashrom release new enough to contain all the chip definitions, otherwise the right move is to leave RPI_EEPROM_IMMEDIATE_UPDATE unset and rely on the staged path.

BCM2711 needs a device tree change before flashrom works at all

On the Raspberry Pi 5, 500, 500+ and CM5, which are BCM2712, no config.txt changes are needed. You set RPI_EEPROM_IMMEDIATE_UPDATE=1 in /etc/default/rpi-eeprom-update, and the tool uses rpi-eeprom-ab if AB EEPROM is enabled and flashrom otherwise.

On the Raspberry Pi 4 and 400, which are BCM2711, flashrom is disabled by default because the SPI GPIOs are shared with the analog audio output. To enable it you set RPI_EEPROM_IMMEDIATE_UPDATE=1 and add to config.txt:

dtparam=spi=on
dtoverlay=audremap
dtoverlay=spi-gpio40-45

The README states plainly that this moves analog audio to GPIO 12 and 13 and may be incompatible with some HATs. That is a real trade-off rather than a formality, because a board with a HAT that uses those pins loses a feature permanently.

The Compute Module 4 and 4S have a different rule again. rpi-eeprom-update is disabled by default on CM4 and CM4S, and the recommended update path is usbboot. To use flashrom instead you need both in /etc/default/rpi-eeprom-update:

RPI_EEPROM_IMMEDIATE_UPDATE=1
CM4_ENABLE_RPI_EEPROM_UPDATE=1

and in config.txt, under a section header:

[cm4]
dtparam=spi=on
dtoverlay=audremap
dtoverlay=spi-gpio40-45

For the CM4S, replace [cm4] with [cms] and add dtparam=enable_eeprom=on.

Minimum bootloader version stops a new board running an old image

The MIN_BOOT_VER section explains a mechanism that is easy to miss and expensive to learn about the hard way.

Newer Raspberry Pi boards may depend on bootloader fixes for hardware that did not exist when older EEPROM releases were built, for example new SDRAM part numbers, revised power-supply sequencing or PMIC behaviour. Installing an EEPROM image that pre-dates the board can leave it unable to boot reliably, or at all.

The protection is a minimum version recorded at manufacture. The board manufacture process programs a minimum bootloader version into the device, exposed by the firmware in the device tree at /proc/device-tree/chosen/rpi-min-boot-ver. Each EEPROM image embeds a corresponding MFG_VER: field, and rpi-eeprom-update compares them, so an image older than the board's minimum is refused.

This is the sort of mechanism that only matters when a new board revision appears, and it is the reason the repository tracks a separate release per SoC family rather than shipping one image. It also explains the release naming: the recent tags are v2026.09.25-2712, v2026.09.23-2711-0138c0 and v2026.05.17-2711-0138c0, with the family number and a build hash in the name.

The rpi-bootloader-version file at the repository root and the releases.md file record the version history, and the recent releases include both recovery images and the versioned EEPROM images themselves.

The tooling covers custom configs and signed boot images

Beyond the updater, the repository carries the tools for anyone who needs to build a custom or signed bootloader, and the set is more substantial than a version-check script.

rpi-eeprom-config operates on an EEPROM image. It can extract the bootconf.txt configuration block with rpi-eeprom-config pieeprom.bin --out boot.conf, write a new image with a replacement config using --config boot.conf --out new.bin pieeprom.bin, edit the installed bootloader's config in place with sudo -E rpi-eeprom-config --edit, embed a signed config block plus an RSA public key for signed boot with --config, --digest and --pubkey, and replace the signed bootcode and bootsys sub-binaries inside a BCM2712 image with --bootcode and --bootsys.

rpi-eeprom-digest generates the .sig files, which are SHA256 plus a timestamp and optionally an RSA PKCS#1 v1.5 signature for signed boot. There are two of them, bootconf.sig produced when building a signed EEPROM image so the bootloader can verify its own configuration block, and boot.sig produced alongside the secure-boot boot.img ramdisk so the bootloader can verify the OS payload at boot. Signing is delegated to openssl as a soft dependency, or to an external HSM via the -H hsm-wrapper interface.

tools/rpi-sign-bootcode is customer signing for the bootloader's own second-stage binary. On BCM2712 it counter-signs the Raspberry-Pi-signed bootcode and bootsys with the customer key, which the BCM2712 ROM requires when secure boot is enabled, and on BCM2711 it produces the HMAC plus RSA-signed second-stage image.

Two tools are marked deprecated. tools/rpi-otp-private-key reads or writes the device-unique private key stored in OTP, and the README directs you to rpi-fw-crypto from the raspberrypi/utils repository instead. tools/vl805 is the updater for the VL805 USB 3.0 controller firmware on early Pi 4 boards with a dedicated VL805 EEPROM, since newer board revisions embed the VLI firmware in the bootloader EEPROM and do not need it.

Where rpi-eeprom is the wrong tool

The first wrong-tool case is a user whose board boots fine. The staged update path runs from a systemd service on Raspberry Pi OS, so the ordinary owner never needs this repository at all, and pulling a bootloader image by hand onto a working board adds risk for no benefit.

The second is a board with a custom kernel that has to keep working. The bootloader and the kernel are two halves of the same boot contract, and an EEPROM that changes the expected boot protocol, the device tree handling or the memory timing can stop a kernel that worked yesterday. The MIN_BOOT_VER mechanism exists to stop the board from accepting an image that is too old, but it does not stop you from installing an image that is too new for your kernel.

The third is a non-Linux or non-Raspberry Pi OS system. The tool expects a Raspberry Pi OS environment with a boot partition, a recovery.bin in the right place and a systemd service definition. The README is explicit that on other distributions you need the patched flashrom build or a recent enough release, and that otherwise the staged path is the fallback.

The fourth is the CM4 case specifically. On Compute Module 4 and 4S the updater is disabled by default and usbboot is the recommended path, so using flashrom there means enabling an update path that the vendor did not enable, on a module that usually gets its bootloader written by the manufacturing or deployment process rather than by the operating system.

Editorial conclusion

rpi-eeprom fits a Raspberry Pi owner who needs the latest bootloader, a custom boot configuration, or signed boot images for a fleet of boards. It does not fit a user who simply wants their Pi to boot, since the staged update path already handles that. Before running an immediate flashrom update, read the BCM2711 SPI requirements, because the GPIO pins are shared with the analog audio output and enabling it needs a device tree change that may conflict with a HAT.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. raspberrypi/rpi-eeprom on GitHub
4. README
5. Releases