To get a Raspberry Pi up and running, you need to download the latest operating system (OS) release image, burn it to an SD card, slide the card into the Pi, and power it up. After the Pi boots, you log in with the default credentials and run sudo raspi-config to configure WiFi, locale, keyboard, and time zone and to enable SSH, I2C, a camera, and whatever else you need for I/O. Next, you update the OS with sudo apt update, sudo apt upgrade, and reboot before finally logging back in and installing all your favorite software that is not installed on the base image.

For casual Pi users, this procedure is a one-time or rare task. However, for experienced makers who have gone through this drill dozens – if not hundreds – of times, it is a real pain.

In this article, I present a method to create your own custom Raspberry Pi OS image that is just under 2GB in size, making it very fast to burn to any size SD card. No more waiting for an 8 or 16GB image to burn. This custom image not only burns fast, but when it boots, it expands the root filesystem to the full size of the target SD card. When the boot completes, you have a clean Pi OS system with your preferred customizations. No more raspi-config and wasting time installing your preferred software.

A custom OS on an SD card is a huge time saver if you need to create clean Raspberry Pi OS systems to test software installation scripts. If you burn a lot of Pi OS images in your lab, you will wonder how you got along without this capability in your toolbox.

Most makers never think about the first-time boot of a Raspberry Pi OS image. Behind the familiar on-screen Raspberries, one for each CPU core, and the brief display that says Resized root filesystem … a lot is happening. (See the "One-Time Partition Resizing" box.)

One-Time Partition Resizing

Figure 1 provides a simplified view of the root partition resize process. When the Raspberry Pi first boots, it reads command-line parameters from the /boot/cmdline.txt file (step 1), with parameters for the output console, TTY speed, root partition ID, and so on.

Figure 1: Raspberry Pi OS partition resize process.

In step 2, the init_resize.sh script performs a number of housekeeping chores, such as preparing and mounting the filesystems. Surprisingly, this script does not resize the physical partition; it simply calls the partition editor (parted) to modify the SD card partition table, which determines how big the SD card is and then modifies the second partition entry to expand it to fill the remaining empty space, making the initial resize a quick process. The script also modifies the cmdline.txt file, removing the term quiet plus removing itself so it will never get called again. Once the housekeeping tasks are performed, the script reboots the Pi (step 3).

The task to resize the root filesystem is done by a registered service, the short /etc/init.d/resize2fs_once shell script (step 4), that runs at system init time. This short-lived script does three things: It calls resize2fs to resize the root filesystem to match the partition table modified in step 2 in the flowchart and then performs the other two tasks described in step 5.

Once the root filesystem has been resized, this never has to be done again. In the final step, the partition resize script deletes itself as a registered service and then deletes its own file from the filesystem.

In summary, the root filesystem partition resize task has split responsibilities. An init script executed from the boot command line modifies the SD card partition table to expand the root partition to fill the unused space on the SD card. After a reboot, a registered service physically resizes the partition. This process only needs to run once, so both scripts ensure that they never run again.

Building a Custom OS Image

When you create your super-shiny custom Raspberry Pi OS image, if you do not re-enable the resize process, your image will boot a Pi and work, but it will not automatically resize the root partition to the size of the host SD card. You will have to do it manually, which defeats the whole purpose of the custom image. To create your custom image, you need to do seven things (Table 1). In step 1 it does not matter whether you use the Desktop or Lite Pi OS version.

Burn the Base Image

Again, this is the standard drill we all know and love [2]. It does not matter how big the SD card is as long as the base OS image will fit on it.

Prevent Auto-Resizing

Why would you want to prevent automatically resizing the root partition? Because you want your custom image to be as small as possible. In fact, your custom image will be close to the same size as the Raspberry Pi OS base image – that is, OS Lite (2GB), OS with desktop (4GB), or OS with desktop and recommended software (9GB).

When you burn your custom image to an SD card, the smaller the image, the faster it burns. Image burn time really ads up when you have 8, 16, or 32GB images to burn.

Once you have burned the base OS image to an SD card in a card adapter, plug the card into a USB port on your Linux host. I run Ubuntu Linux on my laptop, and when I plug in a Raspberry Pi OS SD card, it mounts both partitions (/boot and /rootfs) automatically. The OS Lite image partition layout is shown in Figure 2.

Figure 2: Raspberry Pi OS Lite partition layout.

If your system does not mount the partitions, you will have to do it manually. You are only interested in mounting the /boot partition (partition 1). On my system, the SD card with the base Pi OS image is device /dev/sda.

To mount the first partition (/boot), I entered:

$ sudo mkdir /media/sdcard
$ sudo mount -o,rw /dev/sda1 /media/sdcard

Now the /boot partition of the SD card is mounted on /media/sdcard. (Be sure to change the mount command to match the device ID for your image.)

Once the /boot partition is mounted (Figure 3a), edit the file named cmdline.txt by opening the file in your favorite editor. If you used sudo to mount the partition, then you will need to be root to edit any files.

Figure 3: (a) Mounted /boot partition. (b) /root partition layout. (c) Resized root partition.

The cmdline.txt file contains only one line. The init command at the end of the line needs to be removed before you save the file. Be sure you do not add a newline and create a second, empty line, which will break the script.

Now, to unmount the image, use the command:

$ sudo umount /media/sdcard