A reliable, modern toolkit for backing up, shrinking, restoring, and verifying Raspberry Pi SD card images — entirely from your Linux host machine.

The traditional dd | gzip workflow is slow and wastes space copying empty blocks. Legacy tools like PiShrink bundle compression with shrinking and inject /etc/rc.local scripts to auto-expand on first boot — a technique that breaks on modern distros like Ubuntu 22.10+.

This project fixes both problems:

1. pi_image_manager.sh — Interactive manager handling I/O, hashing, zstd compression, and host-side partition expansion.
2. pishrink_v2.sh — Standalone shrink tool that only resizes the ext4 filesystem & partition. No compression, no boot-script injection.

Instead of hoping an injected script runs on the Pi's first boot, the restore operation expands the partition and filesystem immediately while the SD card is still plugged into the host machine. The card is ready to boot at full capacity — no first-boot surprises.

Install everything on Debian/Ubuntu:

sudo apt install parted e2fsprogs util-linux zstd coreutils

# Clone / download the scripts git clone <repo-url> && cd rpi-image-manager # Make executable chmod +x pi_image_manager.sh pishrink_v2.sh # Launch the manager (requires sudo) sudo ./pi_image_manager.sh

You'll see an interactive menu:

╔══════════════════════════════════════════════════╗ ║ 🍓 Raspberry Pi SD Card Image Manager v1.0.0 ║ ╚══════════════════════════════════════════════════╝ 1) Find SD Card Path 2) Create Backup (dd → shrink → zstd) 3) Restore Image (verify → write → expand) 4) Verify Image (SHA256 check) q) Quit 

Scans block devices and filters out your host root disk so you can't accidentally pick it. Highlights likely removable targets.

Workflow: dd → pishrink_v2.sh → sha256sum + zstd → .meta

# Example session: # Input device path: /dev/sda # Output name: ubuntu_22_backup # Output directory: /backups # # Result: # /backups/ubuntu_22_backup.img.zst (compressed image) # /backups/ubuntu_22_backup.img.zst.meta (integrity metadata)

The .meta file contains:

RAW_SHA256=abc123... COMPRESSED_SHA256=def456... COMPRESSION_ALGO=zstd 

Workflow: verify .meta → zstdcat | dd → parted resizepart → e2fsck → resize2fs

The partition is expanded to fill the SD card on the host machine — no first-boot expansion needed.

Reads the .meta file and re-hashes the .zst to confirm integrity.

pishrink_v2.sh can be used independently:

# Verbose mode (default) — see every step sudo ./pishrink_v2.sh my_image.img # Quiet mode — suppress terminal output (logfile still created) sudo ./pishrink_v2.sh -q my_image.img

A detailed logfile (pishrink_YYYYMMDD_HHMMSS.log) is always written to the current directory.

1. Reads partition layout with parted
2. Attaches the rootfs via losetup
3. Reads filesystem metadata with tune2fs
4. Checks filesystem integrity with e2fsck
5. Calculates minimum size with resize2fs -P
6. Adds a safety padding margin
7. Shrinks the filesystem with resize2fs
8. Rebuilds the partition table with parted
9. Truncates trailing empty space from the image file

Standard two-partition Raspberry Pi layout:

Partition 1: boot (FAT32, ~256M) Partition 2: rootfs (ext4, remainder) ← target for shrink/expand 

This project was developed with the assistance of AI, translating the author's technical design and requirements into a functional implementation.

The functional specification and "living prompt" used to design and build this project is stored in prompts/specification.md. This file serves as the source of truth for the project's features and safety requirements.

MIT