[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.

Bravo88

Hi thanks for letting me know and indeed even with those errors, I was able to create a IMG. I'm still using it for cross-compile it for my raspberry 3.

I finally had some time to dive further into this my project.
But the script looks like it's no longer building on Debian. Do you have an idea why?

Sadly, I could not create an issue on your git.

This is my console:

Ensure at least 8GB of free storage (workspace + final image).
Cloning RetroPie-Setup...
Cloning into 'rp_build_image'...
remote: Enumerating objects: 472, done.
remote: Counting objects: 100% (472/472), done.
remote: Compressing objects: 100% (407/407), done.
remote: Total 472 (delta 76), reused 224 (delta 43), pack-reused 0 (from 0)
Receiving objects: 100% (472/472), 1.83 MiB | 8.48 MiB/s, done.
Resolving deltas: 100% (76/76), done.
Installing dependencies...

= = = = = = = = = = = = = = = = = = = = =
Installing dependencies for 'image' : Create/Manage RetroPie images
= = = = = = = = = = = = = = = = = = = = =

Creating chroot image...

= = = = = = = = = = = = = = = = = = = = =
Running action 'create_chroot' for 'image' : Create/Manage RetroPie images
= = = = = = = = = = = = = = = = = = = = =

/home/user/rp_build_local/rp_build_image/tmp/build/image /home/user/rp_build_local/rp_build_image
Downloading https://downloads.raspberrypi.org/raspios_lite_arm64_latest to rpios-bookworm.img.xz ...
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   318  100   318    0     0   3776      0 --:--:-- --:--:-- --:--:--  3831
100  422M  100  422M    0     0  62.1M      0  0:00:06  0:00:06 --:--:-- 68.0M
rpios-bookworm.img.xz (1/1)
  100 %     422.6 MiB / 2,632.0 MiB = 0.161   172 MiB/s       0:15             
Creating chroot from rpios-bookworm.img ...
/home/user/rp_build_local/rp_build_image
Installing RetroPie packages...

= = = = = = = = = = = = = = = = = = = = =
Running action 'install_rp' for 'image' : Create/Manage RetroPie images
= = = = = = = = = = = = = = = = = = = = =


= = = = = = = = = = = = = = = = = = = = =
Running action 'chroot' for 'image' : Create/Manage RetroPie images
= = = = = = = = = = = = = = = = = = = = =

Chrooting to /home/user/rp_build_local/rp_build_image/tmp/build/image/rpios-bookworm ...
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
/home/pi/install.sh: line 10: git: command not found
/home/pi/install.sh: line 11: cd: RetroPie-Setup: No such file or directory
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo: effective uid is not 0, is /usr/bin/sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
Creating final RetroPie image...

= = = = = = = = = = = = = = = = = = = = =
Running action 'create' for 'image' : Create/Manage RetroPie images
= = = = = = = = = = = = = = = = = = = = =

Bravo88

Small update. On Ubuntu, it just runs fine. I'm now building an IMG for a rpi3 :O

Lolonois

@Bravo88 according to the error message it is most likely something on your side. I do not encounter that error in my setup (Rpi5 with vanilla RaspiOS 12 Lite and vanilla RetroPie setup).

I assume you have mounted the working directory for image creation on a separate partition, which lacks execution for root. I would check the respective documentation on how to enable execution for root on the partition in question to remediate.

[Howto] Create a Bookworm RetroPie Image, hands free

Preparation

Inside rp_build_image/ folder

That' all folks!

Inside `rp_build_image/` folder