pi-gen is a tool for building custom Raspberry Pi OS images.
The tool solves the problem of creating consistent, reproducible Raspberry Pi OS distributions by automating the image build process. It works by sourcing configuration from a bash shell fragment that sets environment variables controlling the build, then executing a build script that constructs the image according to those settings. The tool supports building both 32-bit images based on Raspbian and 64-bit images based on Debian, with separate branches for each architecture. Users configure the build by setting variables like IMG_NAME for the output image name, RELEASE to specify the Debian release version, and optional settings like APT_PROXY for package management during builds.
The tool runs on Debian-based operating systems released after 2017, though Docker builds are available for other Linux distributions. It requires careful setup: the repository must be cloned to a path without spaces, as debootstrap does not support such paths. The tool is most suitable for developers and maintainers who need to produce custom Raspberry Pi OS variants or who want to build official images. Those building 32-bit images should use the master branch, while 64-bit builds require the arm64 branch. The configuration system allows flexibility through environment variables, including support for temporary apt repositories during builds and apt proxies for development workflows.
The project maintains active development with regular updates to support current Debian releases. The codebase is written primarily in shell script, reflecting its role as a build automation tool. Documentation in the README covers dependencies, configuration options, and build procedures, though it notes that changing the BASE_DIR variable from its default will likely break the build script.
