A lightweight tool to customize Raspberry Pi OS images by patching the boot (FAT) partition — without mounting the image or rebuilding the system.
rpi-imgpatcher allows you to modify Raspberry Pi OS .img files in a simple, deterministic way.
Instead of:
- mounting disk images
- using loop devices
- rebuilding full images with tools like Yocto or Buildroot
This tool focuses on a much simpler workflow:
Extract → Patch → Reassemble → Flash
It operates directly on the boot partition (FAT), enabling you to inject files and configuration that will be applied on first boot.
Provisioning Raspberry Pi systems at scale is surprisingly painful.
Typical approaches involve:
- fragile shell scripts
- manual file copies
- post-flash SSH setup
- complex image build systems
rpi-imgpatcher aims to provide a clean middle ground:
- no full rebuilds
- no manual mounting
- reproducible image customization
- Extract boot partition from
.img - Modify FAT filesystem safely
- Inject files before first boot
- Deterministic image patching
- CLI interface
- Optional declarative patch format (à la Dockerfile)
rpi-imgpatcher supports .xz archives as both inputs and outputs.
In practice, using an .xz file as the output format is usually a poor choice. Writing compressed images is significantly slower than writing plain .img files, and the resulting archive must still be decompressed before flashing.
Here is a simple benchmark I ran using the same input image, once with a plain .img output and once with an .img.xz output:
$ time NAME=testred cargo run --release
Finished release profile [optimized] target(s) in 0.11s
Running target/release/rpi-imgpatcher
________________________________________________________
Executed in 5.79 secs fish external
usr time 0.21 secs 0.36 millis 0.21 secs
sys time 3.74 secs 1.22 millis 3.74 secs
$ time NAME=testredxz cargo run --release
Finished release profile [optimized] target(s) in 0.12s
Running target/release/rpi-imgpatcher
________________________________________________________
Executed in 58.12 secs fish external
usr time 49.67 secs 0.43 millis 49.67 secs
sys time 4.34 secs 1.91 millis 4.34 secsFor most workflows, .xz is best used as an input format or as a storage/archive format, not as the final output of the patching step.
--
- Modifying the root filesystem (ext4)
- Rebuilding full OS images
- Replacing tools like Yocto / Buildroot
Instead, the focus is on:
First-boot provisioning via boot partition patching
🚧 Early development
This project is being built incrementally using:
- GitHub issues for each step
- small, testable milestones
- a core-first approach (Rust)
The API and CLI are not stable yet.
- Core image parsing
- FAT extraction and modification
- File injection
- CLI tool
- Validation and safety checks
- Declarative patch format (Patcherfile)
- FFI bindings
- Support for .xz archives
Keep it simple.
- Prefer patching over rebuilding
- Prefer deterministic workflows over scripts
- Avoid unnecessary complexity
This project is not affiliated with the Raspberry Pi Foundation.
MIT