rpi-image-gen

rpi-image-gen is a tool for creating custom software images for Raspberry Pi devices. It runs best on a Raspberry Pi Host running up-to-date 64-bit Raspberry Pi OS.

For the tool used to create the Raspberry Pi OS distribution, please go to https://github.com/RPi-Distro/pi-gen

NOTE rpi-image-gen is under active development. Please report issues at https://github.com/raspberrypi/rpi-image-gen. Feature suggestions are welcome.

Quick Start

From Source

git clone https://github.com/raspberrypi/rpi-image-gen.git
cd rpi-image-gen
sudo ./install_deps.sh
./rpi-image-gen build -c ./config/bookworm-minbase.cfg

The device image will be in ./work/image-deb12-arm64-min/deb12-arm64-min.img

Install it onto an SD card using Raspberry Pi Imager (https://www.raspberrypi.com/software/). Select "Use Custom" if using the GUI, or use the command line:

sudo rpi-imager --cli ./work/image-deb12-arm64-min/deb12-arm64-min.img /dev/mmcblk0

Note: This image intentionally has login passwords disabled.

To install via other means, for example using rpiboot with pi-gen-micro's usb mass-storage or fastboot gadget, or provisioning with rpi-sb-provisioner, take a look at the documentation in those repositories.

The rpi-image-gen technical documentation and examples directory provide customisation and usage guidance.

Why use this?

• Fast builds - Uses pre-built packages instead of building from source

• Production-ready - Same binaries used by millions in production worldwide

• Compatible - Use the same library versions as Raspberry Pi OS

• Customisable - Configure your filesystem exactly as needed

• Secure - Integrate with rpi-sb-provisioner (https://github.com/raspberrypi/rpi-sb-provisioner) to automatically set up signed boot and encrypted filesystems

• Auditable - Generate Software Bill of Materials and CVE reports to give consumers of your image confidence

rpi-image-gen is a versatile image generation and build automation tool designed to create reproducible operating system artefacts. It supports producing bootable disk images, partitioned media layouts, and device-agnostic filesystem tarballs from declarative configurations. The tool integrates package management, filesystem assembly, and image layout definition, enabling consistent builds for embedded devices, virtual machines, and general-purpose systems. By separating build logic from target hardware specifics, it simplifies cross-platform image creation, CI workflows, and distribution packaging.

Core Concepts

• Configuration - Declare variables and build attributes in simple, easy to read files

• Layers - Modular, composable components with automatic variable checking, validation policies and comprehensive documentation

• Hooks - Shell scripts that run at defined points in the build process

Architecture

rpi-image-gen uses:

• bdebstrap (https://github.com/bdrung/bdebstrap) for modular layer application

• mmdebstrap (https://gitlab.mister-muffin.de/josch/mmdebstrap) for filesystem construction

• genimage (https://github.com/pengutronix/genimage/) for disk image creation

• YAML for file-based configuration

• podman unshare to handle filesystem ownership correctly using linux namespaces

The tool runs as a regular user and does not require root privileges.

Dependencies

Install required base dependencies:

sudo ./install_deps.sh

See the depends file for the complete list of required packages.

Important

rpi-image-gen has been developed on Raspberry Pi OS which, at the time of writing, is Debian Bookworm arm64. It heavily favours Debian-based systems and will run on non-arm64 platforms (such as x86_64) via QEMU emulation or inside container environments. However, there is currently no formal support for these non-native environments.

If utilising sparse images in your workflow, e.g. with rpi-sb-provisioner (https://github.com/raspberrypi/rpi-sb-provisioner), please refer to the provisioning documentation for important advice.

Documentation

Technical Information

• Index - Comprehensive reference for the configuration system, layer management, metadata, variable validation, provisioning, execution flow, etc.

Examples

See the examples/ directory for tips and help

Directory Structure:

• bin/ - Common executable files and utilities

• config/ - Configuration files

• device/ - Device specific assets

• docs/ - Technical documentation

• examples/ - Examples and howto

• image/ - Disk layout specific assets

• keydir/ - Cryptographic assets

• layer/ - Layer library

• layer-hooks/ - Common hooks used by layer library

• lib/ - Execution helpers and macros, eg CLI handling, reusable constructs

• scripts/ - Dedicated functional hooks, eg for bdebstrap

• site/ - Core Python engine classes

• templates/ - Templating assets, eg doc generation

• test/ - Test harness

Basic Usage

# Building
rpi-image-gen build -c config/my-system.yaml

# Specify the source directory
rpi-image-gen build -S /path/to/my/assets -c /path/to/my/config.yaml

# List all available layers
rpi-image-gen layer --list

# Describe a layer
rpi-image-gen layer --describe my-layer

# Lint a layer file when developing a custom solution
rpi-image-gen metadata --lint /path/to/my/layer.yaml

# See all options
rpi-image-gen --help

Integration

rpi-image-gen is designed for integration with external build systems:

• External directories can provide custom configs and layers

• Reusable components allow developers to easily apply their customisations on top of built-in defaults

• Hooks provide integration points throughout the build process

• SBOM generation for security and compliance workflows

Getting Help

• Documentation: Technical reference index

• Issues: https://github.com/raspberrypi/rpi-image-gen/issues

• Examples: examples/ directory

• Layer reference: rpi-image-gen layer --help