[Howto] Create a Bookworm RetroPie Image, hands free

[Lolonois]

Automate the boring stuff with ~Python~ RetroPie-Setup!

Following is an approach to create a ARM64 bookworm image from within RetroPie-Setup. It requires no manual interaction. So kick it off, take a walk with your dog (or do something else) and when you are back the image is ready. In essence it only takes three RetroPie-Setup calls.

The scriptmodule image.sh has been around quite a while and all kudos go to the RetroPie maintainers. I just made some changes to run it also for the aarch64 / Bookworm combo. It is not perfect, but it works and you don't have to ask others to provide an image or deal with download limitations. Additionally you can customize the image to your needs.

You don't have to run the script on your Raspberry Pi, as the image.sh utilizes Qemu in user-mode for the image creation when running on an Intel PC (as long as the Desktop provides a Linux context, ofc). Roughly speaking: Qemu in user-mode on an Intel architecture is like Box64 on an ARM architecture but in reverse.

For my tests I utilized a Rpi5 4GB running on a SD-card. The image was done in one hour. If you have a beefy Desktop or use cloud instances it may even process faster.

Enough pre-text, here is how.

Preparation

Checkout the branch and install the base dependencies for the image creation process.

git clone -b fb_image_sh_bookworm_aarch64 --depth 1 https://github.com/Gemba/RetroPie-Setup.git rp_build_image
cd rp_build_image
sudo ./retropie_packages.sh image depends

Inside rp_build_image/ folder

Make sure you have at least 8GiB of free storage (~4 GiB as workspace, <4GiB for final *.img file).

Then run these commands (note the comment):

# Note: Not all platforms do support 64 bit
# https://www.raspberrypi.com/documentation/computers/config_txt.html#arm_64bit
arm64="1" # set 1, if 64bit setup (aarch64) is wanted, 0 uses 32bit (armhf)

dist="bookworm"
platform="rpi5"

[[ "$arm64" -eq 1 ]] && sed -i "s/_armhf_/_arm64_/" "scriptmodules/admin/image/dists/rpios-$dist.ini"
[[ "$arm64" -eq 0 ]] && sed -i "s/_arm64_/_armhf_/" "scriptmodules/admin/image/dists/rpios-$dist.ini"

sudo ./retropie_packages.sh image create_chroot "rpios-$dist"
sudo ./retropie_packages.sh image install_rp $platform "rpios-$dist"
sudo ./retropie_packages.sh image create "$(pwd)/tmp/build/image/rpios-$dist.img" "$(pwd)/tmp/build/image/rpios-$dist"

Now take care of your pet and come back after a while.

That' all folks!

The image file is tmp/build/image/rpios-bookworm.img. Take this to put it on a SD-card (dd, Raspberry Pi Imager, Etcher, ...). With Rpi Imager you can apply the usual customizations (SSH, wireless, timezone, ...).

The image reboots once after Generating SSH Keys and then you will be greeted with RetroPie/EmulationStation. :)

Final notes:

• If you want to add OS packages customize this line,
• for changing RetroPie-Setup packages see these lines.
• You can also copy config files from your current RetroPie-Setup if needed (i.e. Gamecontroller config) to the image after the install.sh has been run, thus after this line.
• You have to clean the image build folder, if you want to use a newer upstream RaspiOS base image or change the architecture (arm64/armhf): sudo ./retropie_packages.sh image clean

Have fun with your "golden image"!

[sugarfree]

Wow, this is amazing and very helpful. Thank you very much!

[Bravo88]

Hi, I wanted to run your script in a virtual machine (Debian) and I used these commands like mentioned (I've created a script for it).

I'm building it for a raspberry 3

#!/bin/bash

# Auto-create a RetroPie image for Raspberry Pi (Bookworm)
echo "Ensure at least 8GB of free storage (workspace + final image)."

# Step 1: Clone RetroPie-Setup repository
echo "Cloning RetroPie-Setup..."
git clone -b fb_image_sh_bookworm_aarch64 --depth 1 https://github.com/Gemba/RetroPie-Setup.git rp_build_image
cd rp_build_image

# Step 2: Install dependencies
echo "Installing dependencies..."
sudo ./retropie_packages.sh image depends

# Step 3: Set platform & distribution
arm64="1"  # 1 = 64-bit (aarch64), 0 = 32-bit (armhf)
dist="bookworm"
platform="rpi3"  # Adjust for your Raspberry Pi model

# Update config based on architecture
[[ "$arm64" -eq 1 ]] && sed -i "s/_armhf_/_arm64_/" "scriptmodules/admin/image/dists/rpios-$dist.ini" || sed -i "s/_arm64_/_armhf_/" "scriptmodules/admin/image/dists/rpios-$dist.ini"

# Step 4: Create chroot image
echo "Creating chroot image..."
sudo ./retropie_packages.sh image create_chroot "rpios-$dist"

# Step 5: Install RetroPie packages
echo "Installing RetroPie packages..."
sudo ./retropie_packages.sh image install_rp $platform "rpios-$dist"

# Step 6: Generate final image
echo "Creating final RetroPie image..."
sudo ./retropie_packages.sh image create "$(pwd)/tmp/build/image/rpios-$dist.img" "$(pwd)/tmp/build/image/rpios-$dist"

# Step 7: Done!
echo "RetroPie image created: $(pwd)/tmp/build/image/rpios-$dist.img"
echo "Flash it to an SD card using dd, Raspberry Pi Imager, or Etcher."
echo "Installation complete! Enjoy RetroPie!"

Now on my machine I get a lot of errors, like:

sed-but-set-variable]
   94 |         int tmp;
      |             ^~~
../../cpu/m6502/tdeco16.c: In function ‘void deco16_a3()’:
../../cpu/m6502/tdeco16.c:104:13: warning: variable ‘tmp’ set but not used [-Wunused-but-set-variable]
  104 |         int tmp;
      |             ^~~
../../cpu/m6502/tdeco16.c: In function ‘void deco16_13()’:
../../cpu/m6502/tdeco16.c:115:14: warning: variable ‘tmp’ set but not used [-Wunused-but-set-variable]
  115 | OP(13) { int tmp; m6502_ICount -= 1; RD_IMM;
      |              ^~~
../../cpu/m6502/tdeco16.c: In function ‘void deco16_87()’:
../../cpu/m6502/tdeco16.c:197:14: warning: variable ‘tmp’ set but not used [-Wunused-but-set-variable]
  197 | OP(87) { int tmp; m6502_ICount -= 1; RD_IMM;
      |              ^~~

I also saw that a lot of packages were failing. Is the issue that I'm using the wrong distro?
What am I missing? :P

[Lolonois]

I just tried with my fork on a Rpi5 to create a Rpi3 image.

The warnings in creating the chroot image (your step 5) can be ignored.
xpad and usbmount fail with an error but these can be re-installed on the real Pi3 if needed.

When the final image creation (your step 6) fails with something like

device-mapper: reload ioctl on loop0p2 (254:1) failed: Invalid argument
create/reload failed on loop0p2

just run it again.