- Notifications
You must be signed in to change notification settings - Fork76
A tool to generate highly customised software images for Raspberry Pi devices.
License
raspberrypi/rpi-image-gen
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
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 tohttps://github.com/RPi-Distro/pi-gen
NOTE rpi-image-gen is under active development. Please report issues athttps://github.com/raspberrypi/rpi-image-gen. Feature suggestions are welcome.
git clone https://github.com/raspberrypi/rpi-image-gen.gitcd rpi-image-gensudo ./install_deps.sh./rpi-image-gen build -c ./config/bookworm-minbase.yaml
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 usingrpiboot withpi-gen-micro's usb mass-storage or fastboot gadget, or provisioning withrpi-sb-provisioner, take a look at the documentation in those repositories.
The rpi-image-gentechnical documentation andexamples directory provide customisation and usage guidance.
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 withrpi-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.
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
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.
Install required base dependencies:
sudo ./install_deps.sh
See thedepends file for the complete list of required packages.
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. withrpi-sb-provisioner (https://github.com/raspberrypi/rpi-sb-provisioner), please refer to theprovisioning documentation for important advice.
Index - Comprehensive reference for the configuration system, layer management, metadata, variable validation, provisioning, execution flow, etc.
bin/- Common executable files and utilitiesconfig/- Configuration filesdevice/- Device specific assetsdocs/- Technical documentationexamples/- Examples and howtoimage/- Disk layout specific assetskeydir/- Cryptographic assetslayer/- Layer librarylayer-hooks/- Common hooks used by layer librarylib/- Execution helpers and macros, eg CLI handling, reusable constructsscripts/- Dedicated functional hooks, eg for bdebstrapsite/- Core Python engine classestemplates/- Templating assets, eg doc generationtest/- Test harness
# Buildingrpi-image-gen build -c config/my-system.yaml# Specify the source directoryrpi-image-gen build -S /path/to/my/assets -c /path/to/my/config.yaml# List all available layersrpi-image-gen layer --list# Describe a layerrpi-image-gen layer --describe my-layer# Lint a layer file when developing a custom solutionrpi-image-gen metadata --lint /path/to/my/layer.yaml# See all optionsrpi-image-gen --help
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
Documentation:Technical reference index
Examples:
examples/directoryLayer reference:
rpi-image-gen layer --help
About
A tool to generate highly customised software images for Raspberry Pi devices.
Resources
License
Uh oh!
There was an error while loading.Please reload this page.