From the docs:

Previous versions of Raspberry Pi OS made use of a wpa_supplicant.conf file which could be placed into the boot folder to configure wireless network settings. This is no longer possible from Raspberry Pi OS Bookworm onwards.

I'd like to know if there is an alternative method that does not need a GUI application to correctly configure WiFi on the Raspberry Pi OS image.

Question: How can I configure WiFi on an Raspberry Pi headlessly without using the Raspberry Pi Imager in current Raspberry Pi OS images?

  • 2
    what I would do is create an image using the RPi Imager with the settings you want, then check the boot partition for a file called firstrun.sh - you'll see what needs to be done - also check cmdline.txt to see how firstrun.sh is being executed - everything you need to know is in the file /usr/lib/raspberrypi-sys-mods/imager_custom if you can read shell scripts Nov 2, 2023 at 23:36
  • Good question... absent any explanation from the "pi guys", I'd say that's a pretty shitty move... in effect requiring use of their RPi Imager app to create a bootable SD that works for headless versions of the OS. (I define bootable as capable of hosting an SSH connection via Enet or WiFi.) I've not yet tried to install 'bookworm' so I've not had to deal with this. It's possible this is something they've not gotten around to yet - we'll see shortly. In the meantime, I'd try @JaromandaX 's suggestions.
    – Seamus
    Nov 3, 2023 at 0:09
  • I just added wifi (I had it turned off) on a pi running bookworm by running sudo /usr/lib/raspberrypi-sys-mods/imager_custom set_wlan 'ssid' 'psk' 'CC' (I hope the actual values to use are obvious) - then rebooted Nov 3, 2023 at 0:12

3 Answers 3


With Raspberry Pi OS bookworm you can configure WiFi via a custom.toml that you place in the bootfs partition (first boot only).

Note that this feature is experimental and will be replaced by cloud-init in the future.

An example gist and blog explains some of the options:

I am copying the example from the aforementioned gist (not affiliated):

# Required:
config_version = 1

hostname = "raspberrypi"

# If present, the default "rpi" user gets renamed to this "name"
name = "rpi"
# The password can be encrypted or plain. To encrypt, we can use "openssl passwd -5 raspberry"
password = "$5$pN7oRnie.WDOHoJY$aWEYmKUytN/S/bxMza5ksBiurbSJmcvcysBKHSmYa45"
password_encrypted = true

# ssh_import_id = "gh:user" # import public keys from github
enabled = true
password_authentication = false
# We can also seed the ssh public keys configured for the default user:
# authorized_keys = [ "ssh-rsa ... user@host", ... ]

ssid = "mywifi"
password = "$5$pN7oRnie.WDOHoJY$aWEYmKUytN/S/bxMza5ksBiurbSJmcvcysBKHSmYa45"
password_encrypted = true
hidden = false
# The country is written to /etc/default/crda
# Reference: https://wireless.wiki.kernel.org/en/developers/Regulatory
country = "IE"

keymap = "gb"
timezone = "Europe/London"

You could dig more into the firstboot or init_config scripts (the latter is what loads the config).


Bookworm now uses NetworkManager for networking.

If you preconfigure during the imaging process you can set the hostname, user/password, Locale, wireless networking and enable ssh.

For some time Raspberry Pi OS has required that a user be generated on first boot - Raspberry Pi Imager can also do this. This was explained in https://www.raspberrypi.com/news/raspberry-pi-bullseye-update-april-2022/

Raspberry Pi Imager modifies cmdline.txt to run a script on boot and writes a customised startup script firstrun.sh which sets whatever is preconfigured.

These files are deleted on first boot.


I'm sharing my steps, which helped me to correctly configure Wifi connection profile for headless RPI installation with Bookworm OS. This was tested on Raspberry Pi ZERO.

  1. download and install Raspberry PI Imager (I'm using v1.8.1, on Ubuntu)

  2. in the Imager GUI, do not select RPI device in the first step. Currently, Pi ZERO is not on the supported list in RPI Imager for Bookworm. This means, you will not be able to flash Bookworm OS, when you select filter for PI ZERO device at first step.

  3. select Raspberry PI OS Lite (32bit Bookworm), if you want to do headless installation

  4. choose your microSD card, the target device for flashing

  5. click next and you will be able to set some settings, like system username and password, hostname, wifi credentials, timezone etc. Configure this settings, without Wifi connection settings. This do no work for Bookworm at this time (december 2023)

  6. Once the card is ready, remove microSD card from the computer and connect it again

  7. If you are using for example Ubuntu, the 2 partitions will be auto mounted - bootfs and rootfs . In this steps we expect, that partitions are mounted as /media/martin/bootfs and /media/martin/rootfs. Change it in the following steps according your needs.

  8. we will activate ssh connection

    $ sudo touch /media/martin/bootfs/ssh

  9. this step I'm not sure if is needed, give it a try

    $ sudo vim /media/martin/rootfs/boot/firmware/firstrun.sh

Write following content: (change do_wifi_country to your country ISO code)

# Stripped back version of the Bookworm firstrun.sh generated by the Raspberry Pi Imager
# also calls raspi-config to set Wifi country, which in turn calls iw on Bookworm
set +e
rfkill unblock wifi
for filename in /var/lib/systemd/rfkill/*:wlan ; do
    echo 0 > $filename
raspi-config nonint do_wifi_country SK
# edited to remove a bug in rpi-imager that is a hangover from Bullseye
# rm -f /boot/firstrun.sh
rm -f /boot/firmware/firstrun.sh
exit 0
  1. generate PSK for your wifi connection settings:

    $ wpa_passphrase networknameSSID yourWifipassword

  2. insert the wifi connection profile Note: Name the file according your wifi SSID

$ sudo vim /media/martin/rootfs/etc/NetworkManager/system-connections/Matho-Wifi.nmconnection






use the following content:

  • replace Matho-Wifi with your SSID name
  • you can keep the uuid the same. If you change it, the syntax need to meet this length and format
  • set psk to the value, you have generated in previous step 10
  1. Apply chmod 600 and chown the profile

    $ sudo chmod -R 600 /media/martin/rootfs/etc/NetworkManager/system-connections/Matho-Wifi.nmconnection

    $ sudo chown -R root:root /media/martin/rootfs/etc/NetworkManager/system-connections/Matho-Wifi.nmconnection

    $ sudo ls -la /media/martin/rootfs/etc/NetworkManager/system-connections/Matho-Wifi.nmconnection

  2. unmount the partitions, for example via Nautilus GUI

  3. insert the microSD card to your RPI ZERO. Give it some time, on my end it took ~6 minutes to be fully booted

  4. connect via ssh with the username and password you have set via RPI Imager tool

  • This worked like a charm for me on a RPI Zero 2W with Bookworm! Thanks!
    – mdev
    Jan 27 at 13:53

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.