Pi Image Shrink
Cuts a Raspberry Pi backup image down to the space actually used, and grows it back on first boot.
- 01Shrink
- 02Grow back on first boot
- 03Compression
- 04Refusing the wrong target
Architecture Overview
A raw copy of a 64 GB card is a 64 GB file even when only 8 GB is in use, because dd copies the empty space too. This shrinks the filesystem and the partition to what is actually there, then plants a first-boot hook that expands it again to fill whatever card it lands on. It is the step that makes an image small enough to publish, and it is the piece the Matter harness image builder hands its output to.
How it works
Core mechanics, failure recovery paths, and system design decisions.
Shrink
Checks the filesystem, resizes it to its minimum, then moves the partition end to match. Getting that end offset right is the whole job — one sector out and the image will not mount.
Grow back on first boot
A hook added inside the image expands the filesystem the first time it starts, so a shrunk image is not a smaller machine, just a smaller file.
Compression
Optionally gzip or xz the result, in parallel where the tool supports it, since a mostly-empty image compresses extremely well.
Refusing the wrong target
The script tests that it was handed a regular file, so pointing it at a block device like /dev/sda fails immediately rather than halfway through resizing a live disk.
Engineering Highlights
- •A 64 GB card becomes a file you can actually upload
- •Expands itself on first boot, so nothing is lost by shrinking
- •Refuses a block device rather than damaging one
- •Distinct exit codes per failure, so a build script can tell what went wrong
- •Integrated as the shrink/ compaction engine in the unified pi-image-tools suite