---
title: "Building pi-gen on CRACI"
source: "https://docs.craci.com/guides/examples/pi-gen/"
---

# Building pi-gen on CRACI

[pi-gen](https://github.com/RPi-Distro/pi-gen) builds Raspberry Pi OS images
using `debootstrap`, which downloads hundreds of ARM `.deb` packages. On the
CRACI runner (x86), this requires QEMU user-mode emulation via `binfmt_misc`.

## Minimal workflow

```yaml
name: pigen

on:
  workflow_dispatch:

env:
  PIGEN_REF: 2025-05-13-raspios-bookworm-armhf

jobs:
  pi-gen:
    runs-on: craci
    steps:
      - name: Build Raspberry Pi OS image
        run: |
          set -eo pipefail

          echo "127.0.0.1 $(hostname)" | sudo tee -a /etc/hosts

          sudo apt-get update
          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
            coreutils quilt parted 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 \
            qemu-user-static

          sudo ln -sf /usr/bin/qemu-arm-static /usr/bin/qemu-arm
          if [ -e /proc/sys/fs/binfmt_misc/qemu-arm ]; then
            echo -1 | sudo tee /proc/sys/fs/binfmt_misc/qemu-arm
          fi
          printf '%s' ':qemu-arm:M::\x7fELF\x01\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x28\x00:\xff\xff\xff\xff\xff\xff\xff\x00\x00\x00\x00\x00\x00\x00\x00\x00\xfe\xff\xff\xff:/usr/bin/qemu-arm-static:OCF' | sudo tee /proc/sys/fs/binfmt_misc/register

          git clone --depth 1 --branch "$PIGEN_REF" https://github.com/RPi-Distro/pi-gen.git
          cd pi-gen

          cat > config <<'EOF'
          IMG_NAME='test-raspios'
          RELEASE='bookworm'
          FIRST_USER_NAME='pi'
          FIRST_USER_PASS='raspberry'
          ENABLE_SSH=1
          STAGE_LIST="stage0 stage1"
          EOF

          CONTINUE=0 sudo -E ./build.sh
```

## Notes

- Builds run under QEMU emulation and are significantly slower than native ARM.
  Stage0 and stage1 can take tens of minutes depending on runner size and
  upstream package download speed.
- The `binfmt_misc` filesystem is pre-mounted by the kernel -- no `modprobe`
  needed.
- The symlink from `qemu-arm-static` to `qemu-arm` satisfies pi-gen's
  dependency check.
- The `F` flag in the binfmt registration ensures the interpreter works
  inside debootstrap chroots.
- Pin `PIGEN_REF` to the pi-gen branch or tag that matches the Raspberry Pi OS
  release being built. For example, Bookworm armhf builds should use a Bookworm
  armhf tag rather than floating `master`.
- If `debootstrap` fails while downloading one `.deb`, check
  `pi-gen/work/<image-name>/stage0/debootstrap.log`. That usually indicates an
  upstream Raspbian mirror, package metadata, or proxy fetch issue rather than a
  QEMU setup problem.