Appearance

Custom Raspberry Pi OS Image Creation Guide ​

Last Updated: February 14, 2025

This guide walks you through the process of preparing your Raspberry Pi Zero W2, exporting the custom OS image to your Mac, and shrinking the image to its bare minimum.

1. Prepare the OS on Your Raspberry Pi ​

1.1 Install & Configure the OS ​

  1. Flash the OS:
    Use Raspberry Pi Imager to flash your SD card with a Raspberry Pi OS (e.g., Raspberry Pi OS Lite).

  2. Initial Setup:
    Boot the Pi and run:

    bash
    sudo raspi-config

    In the configuration tool, you should:

    • Set the hostname, locale, and timezone.
    • Enable SSH (under Interfacing Options).
    • Expand the filesystem (under Advanced Options).

  3. Update Your System:

    bash
    sudo apt update && sudo apt upgrade -y

1.2 Install Custom Software ​

Install any necessary packages and add your custom files/configurations. For example:

bash
# Add your additional custom software installations and configurations here.

1.3 Clean Up Unnecessary Files ​

Clean the system to remove unused packages and logs, which helps reduce the image size:

bash
sudo apt autoremove -y && sudo apt clean
sudo rm -rf /var/log/*
sudo rm -rf /tmp/*
cat /dev/null > ~/.bash_history && history -c

1.4 Zero Out Free Space ​

Fill all free space with zeros to optimize image compression:

bash
sudo dd if=/dev/zero of=/zero.fill bs=4M status=progress
sudo rm -f /zero.fill

Note: The message dd: error writing '/zero.fill': No space left on device is expected. It means the SD card has been completely filled with zeros. Once you see this error, simply remove the temporary file and continue.

Shutdown the Pi:

bash
sudo shutdown now

2. Create the Image on Your Mac ​

2.1 Insert the SD Card ​

Insert your SD card into your Mac using an SD card reader.

2.2 Identify the SD Card ​

Open Terminal and run:

bash
diskutil list

Identify your SD card (e.g., /dev/disk2).

2.3 Unmount the SD Card ​

Unmount the entire SD card:

bash
diskutil unmountDisk /dev/disk2

2.4 Create a Raw Image ​

Clone the SD card using the dd command:

bash
sudo dd if=/dev/rdisk2 of=~/Desktop/raspberrypi.img bs=4m

Tip: Replace rdisk2 with your actual SD card identifier. The resulting .img file will be saved on your desktop.

3. Shrink the Image with PiShrink ​

Since macOS doesn't natively support PiShrink, you have two options:

  1. Install Docker Desktop from Docker's website.

  2. Run PiShrink:

    bash
    docker run --rm -it -v ~/Desktop:/work lukechilds/pishrink /work/raspberrypi.img /work/raspberrypi-shrunk.img

    This command produces a shrunk image (raspberrypi-shrunk.img) on your desktop.

Option B: Using a Linux VM ​

  1. Run a Linux VM (via UTM or VirtualBox).

  2. Transfer raspberrypi.img to the VM.

  3. Install PiShrink:

    bash
    wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
chmod +x pishrink.sh
sudo ./pishrink.sh raspberrypi.img raspberrypi-shrunk.img

  4. Transfer the shrunk image back to your Mac.

4. Verify and (Optional) Compress the Image ​

Verify the Image ​

Check the image details:

bash
hdiutil imageinfo ~/Desktop/raspberrypi-shrunk.img

Compress the Image ​

To further reduce the file size, you can compress it:

bash
zip ~/Desktop/raspberrypi-shrunk.zip ~/Desktop/raspberrypi-shrunk.img

5. Flash the Image to a New SD Card ​

To write the custom image to a new SD card, use:

bash
sudo dd if=~/Desktop/raspberrypi-shrunk.img of=/dev/rdisk2 bs=4m

Note: Ensure that /dev/rdisk2 corresponds to your new SD card. The image works on SD cards that are the same size or larger.

Explanation of the Zero-Fill Step ​

When you run:

bash
sudo dd if=/dev/zero of=/zero.fill bs=4M status=progress

you may see an error:

bash
dd: error writing '/zero.fill': No space left on device

This error is expected and indicates that the free space has been completely filled with zeros. Once this occurs, deleting the file (/zero.fill) frees up the space while leaving the underlying blocks optimized for compression.

For any questions or further assistance, please feel free to reach out!

Happy imaging!