RPi-Distro/pi-gen: The Official Tool for Building Custom Raspberry Pi OS Images

What pi-gen Is and What It Builds

pi-gen is the official build tool for Raspberry Pi OS images. It was derived from the Raspbian project and is maintained by the Raspberry Pi distribution team in the RPi-Distro organization. When the Raspberry Pi Foundation publishes a new Raspberry Pi OS image, pi-gen is the tool that produced it.

The tool builds full, bootable operating system images for Raspberry Pi hardware. Two architectures are supported. The 32-bit armhf images are built from the master branch and are based primarily on Raspbian. The 64-bit arm64 images are built from the arm64 branch and are based primarily on Debian. The README notes explicitly: 32-bit images from master, 64-bit images from arm64. Building 64-bit images from the wrong branch or vice versa is a documented mistake to avoid.

The use case is not running pi-gen once to get an image you could download from the Raspberry Pi website. The value of pi-gen is building custom images: images with pre-installed software, pre-configured settings, modified locales, or a stripped-down stage set that produces a minimal headless image. Organizations deploying Raspberry Pi devices at scale typically use pi-gen to produce a pre-configured image that devices are flashed with before shipping.

What is pi-gen: Build Stages and How They Compose

pi-gen organizes the build into a sequence of six stages: stage0 through stage5. Each stage adds a layer on top of the previous one. Stage 0 bootstraps a minimal Debian environment. Stage 1 installs the core system. Stage 2 produces a Lite image with no desktop. Stages 3, 4, and 5 layer in progressively more software toward a full desktop experience.

Custom images are built by modifying or extending these stages. You can also stop at a specific stage to produce a minimal image. The presence or absence of a SKIP file in a stage directory controls whether that stage is included in the build. A SKIP_IMAGES file in a stage directory suppresses image export at that stage without skipping the build steps.

Each stage directory contains numbered package lists and scripts. The stage runs the scripts in order and installs the listed packages at the appropriate point in the sequence. Custom packages and configuration scripts can be added to the stage directories to include them in the final image. This is the mechanism for pre-installing project-specific software in an automated, reproducible way.

How to use pi-gen: Clone, Configure, and Build

Install the required dependencies on a Debian-based host:

apt install coreutils quilt parted qemu-user-binfmt debootstrap zerofree zip \
dosfstools e2fsprogs libarchive-tools libcap2-bin grep rsync xz-utils file git curl bc \
gpg pigz xxd arch-test bmap-tools kmod

Clone the repository:

git clone https://github.com/RPI-Distro/pi-gen.git

Create a config file in the repository root. The README says build.sh sources this file before the build starts. At minimum you must set IMG_NAME to name your image; the README shows the default as raspios-$RELEASE-$ARCH (for example raspios-trixie-armhf). You can set optional variables such as RELEASE, LOCALE_DEFAULT, TIMEZONE_DEFAULT, and TARGET_HOSTNAME. Then run build.sh.

The output image lands in the DEPLOY_DIR, which defaults to the deploy/ directory. DEPLOY_COMPRESSION defaults to zip, producing a compressed .zip file. Setting DEPLOY_COMPRESSION=none gives a raw .img file.

For Docker, use the provided build-docker.sh script. The Docker image is based on Debian bullseye by default (configurable via the BASE_IMAGE build argument). The work and deploy directories are declared as Docker volumes so the build artifacts persist outside the container.

Key Config Variables and Their Defaults

The config file is the primary customization mechanism. The most commonly changed variables beyond IMG_NAME are the locale and locale-adjacent settings. LOCALE_DEFAULT defaults to en_GB.UTF-8 and sets the system locale. KEYBOARD_KEYMAP defaults to gb and sets the keyboard layout. KEYBOARD_LAYOUT defaults to English (UK). TIMEZONE_DEFAULT defaults to Europe/London. Any custom image intended for deployment outside the UK should set all four of these.

TARGET_HOSTNAME defaults to raspberrypi and sets the hostname baked into the image. FIRST_USER_NAME defaults to pi; by default the setup wizard runs on first boot to let the user choose a password. Setting FIRST_USER_PASS disables the wizard and sets the password directly, though the README notes this user is renamed on first boot unless DISABLE_FIRST_BOOT_USER_RENAME is set to 1.

WORK_DIR controls where the build stages write their working data and defaults to the work/ subdirectory of the repository. This directory grows to tens of gigabytes because it stores a complete copy of the target system for each build stage. The README explicitly warns that if WORK_DIR is on an NTFS partition, the build will probably fail: it must be a native Linux filesystem.

DEPLOY_COMPRESSION accepts none, zip, gz, or xz. COMPRESSION_LEVEL ranges from 0 (no compression, fast) to 9 (maximum compression, slow) and defaults to 6. RELEASE defaults to trixie, the current Debian release; changing it to build against a different Debian release requires checking out the corresponding pi-gen branch.

Known Constraints and Failure Modes

The README documents two path-related constraints that are easy to overlook. First, the repository must be cloned to a path that contains no spaces. The debootstrap tool, which pi-gen uses internally to bootstrap the Debian environment, does not support paths with spaces and will fail in a way that can be confusing to diagnose.

Second, the WORK_DIR must be on a proper Linux filesystem. NTFS is explicitly called out as a known failure. This affects users who run pi-gen in a WSL2 environment on Windows where the working directory is on the Windows filesystem mount rather than the Linux ext4 filesystem: the build will fail. Moving WORK_DIR to a path inside the WSL2 Linux filesystem resolves this.

The qemu dependency in the package list is for building arm images on a non-ARM (x86_64) host. The README notes that native builds (building an armhf image on an armhf machine) are not officially supported. Outside a native environment, qemu-user-binfmt provides the binary format translation needed. If the host's qemu-user binaries are dynamically linked, the README recommends installing qemu-user-static instead.

Builds take a long time and consume significant disk space. Running a complete build through stage 5 for a full desktop image can take 30 to 90 minutes depending on hardware and can consume 20 GB or more in WORK_DIR. Planning storage accordingly is important for automated CI builds.

Comparison to rpi-image-gen and Maintenance Status

RELATED SEARCHES include comparisons to rpi-image-gen, a newer official Raspberry Pi image generation tool. The Raspberry Pi Foundation is developing rpi-image-gen as a successor that uses a different approach to image composition. pi-gen uses a staged Shell script approach accumulated over years of official image builds; rpi-image-gen takes a more declarative configuration model. As of the current date, pi-gen remains the production tool for official Raspberry Pi OS images. Organizations that need to build images today should use pi-gen; teams planning long-term infrastructure should monitor rpi-image-gen's development trajectory.

pi-gen runs on Debian-based operating systems released after 2017. The Docker path makes it usable on other Linux distributions where the native build would fail. The BSD-3-Clause license permits modification and redistribution, including for commercial use, with attribution and without endorsement claims against the Raspberry Pi Foundation.

The last push was on 2026-09-16, consistent with active maintenance. The repository uses a GitLab CI configuration (.gitlab-ci.yml) in addition to the GitHub-hosted code, reflecting that it is part of the Raspberry Pi Foundation's internal infrastructure.

Editorial conclusion

pi-gen is the authoritative tool for building custom Raspberry Pi OS images: it is the same tool the Raspberry Pi Foundation uses for official releases, so a custom image built with it will behave consistently with the official ones. It is not suited for casual one-off customization, since the builds are disk-intensive, time-consuming, and require a Debian-based host or a Docker setup. Before starting a custom build, verify that your WORK_DIR is on a native Linux filesystem and that the clone path contains no spaces, since both are documented failure modes.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. RPi-Distro/pi-gen on GitHub