Headless configuration of Raspberry Pi OS in 2025, specifically Bookworm

rpi_install_headless_2025.md

Headless installation of Raspberry Pi OS on ChromeOS (Bookworm)

This will get you a TF / MicroSD card with preconfigured headless Raspberry Pi OS with:

• hostname configured
• user account and password configured
• wifi network and credentials to connect to Wi-Fi
• SSH enabled
• keyboard layout & timezone set (locale)

This will also work on non-ChromeOS platforms so you don't have to use the Raspberry Pi Imager (e.g. dd on Linux).

You do not need to install the Linux dev environment on ChromeOS to get a preconfigured headless RPi.

Download and write the image

1. Download the applicable image, e.g. 2025-05-13-raspios-bookworm-arm64-lite.img.xz
2. extract the download by double-clicking (ChromeOS will extract .xz files)
3. copy & paste the <YYYY-MM-DD>-raspios-<release>-arm64-lite.img file back out your Downloads
4. change the extension from .img to .bin
5. launch the Chromebook Recovery Utility
6. click the gear icon -> "Use local image" and select the .bin file
7. write the image
8. when complete, the storage volumes bootfs (R/W) and rootfs (RO) will be in the ChromeOS file manager

Add custom.toml

1. edit custom.toml for your desired settings for:
   • Wi-Fi
   • region / locale
   • SSH
   • account
   • hostname
2. save custom.toml to the root of the bootfs partition (it is a FAT32 partition that's R/W on ChromeOS)

Insert the MicroSD / TF card and boot

1. shell script /usr/lib/raspberrypi-sys-mods/firstboot is executed from commmandline.txt on the bootfs partition
2. it will call Python script /usr/lib/raspberrypi-sys-mods/init_config to read custom.toml from the root of the bootfs partition
3. Raspberry Pi will be configured with your settings

custom.toml details

The config can contain encrypted or unencrypted passwords for the user account and WiFi, set the flag password_encrypted=false for cleartext.

Why do you need to use this?

It's up to you. I found it ridiculous that you need to use the Raspberry Pi Imager to get a basic RPi headless installation going. It's a GUI utility and nameless binary you're expected to download and just execute.

There's a lot of misinformation on the internet about the usage of wpa_supplicant.conf and a blank ssh file being created and placed on the boot partition to preconfigure the install. This doesn't work on Raspberry Pi OS after Bullseye. I spent days flashing 10+ times trying to figure this out.

Then I discovered that the Raspberry Pi Imager in GUI mode won't let you output a preconfigured RPi image to disk so that you can then use the ChromeOS Recovery Utility to write it. This isn't useful for Chrome OS because block devices are not exposed in the Linux environement on ChromeOS.

Considering that raspberry Pi is often used in education where ChromeOS is prevalent, there is currently no documented, easy way to quickly set up a headless RPi. Which is crazy.