Configuring devices by hand (flash, boot, SSH in, apt install, copy files) doesn't scale, and no two devices end up identical. Raspberry Pi maintains two tools for building your own image once and flashing it everywhere.
rpi-image-gen: customised Raspberry Pi OS-style images
- Builds from pre-built Raspberry Pi OS packages, so it's fast and uses the same library versions as Raspberry Pi OS.
- Configuration is declarative (YAML config + layers + hooks), so the image is reproducible and reviewable in Git.
- Produces an SBOM and CVE reports for your image.
- Integrates with rpi-sb-provisioner for signed boot and encrypted filesystems.
- Runs as a regular user. The supported build host is native Debian Bookworm/Trixie arm64 (a Raspberry Pi 5 with 64-bit Raspberry Pi OS works). Containers and QEMU may work but are not formally supported.
git clone https://github.com/raspberrypi/rpi-image-gen.git
cd rpi-image-gen
sudo ./install_deps.sh
./rpi-image-gen build -c ./config/trixie-minbase.yaml
The minimal example image has login passwords disabled on purpose. Add your user, SSH keys and services in your own layer before deploying it.
Write the result with Raspberry Pi Imager, also scriptable:
sudo rpi-imager --cli ./work/image-deb13-arm64-min/deb13-arm64-min.img /dev/mmcblk0
Other routes the README names: rpiboot with pi-gen-micro's USB mass-storage/fastboot gadget, or rpi-sb-provisioner for secured fleets.
pi-gen-micro: tiny embedded systems
- Builds very small systems from the same package sources as Raspberry Pi OS, so hardware support stays current.
- Limit firmware and device trees to your targets (
pi3,cm3,cm0,pi4,400,cm4,pi5,500,cm5,02W, or family shorthands such aspi5-family):
pushd $(mktemp -d)
pi-gen-micro-sysroot run fastboot cm5,pi5
- Its README warns that its delete lists run as an unquoted
rm -rf. Under plainsudothat runs as real root against the host, so prefer thepi-gen-micro-sysrootwrapper, which uses a user namespace.
When to use which
| Need | Tool |
|---|---|
| A normal Raspberry Pi OS-like system with your apps and config baked in | rpi-image-gen |
| Minimal appliance or provisioning/recovery image | pi-gen-micro |
| Secure boot + encryption across many devices | rpi-image-gen image deployed with rpi-sb-provisioner |
Keep the image config in version control, and rebuild rather than patching deployed devices by hand.