Raspberry Pi WIFI files in Raspberry Pi OS Bookworm/Trixie

11 Jul 2026

If you’re a normal user, stop reading now and use raspi-config or Raspberry Pi Imager to configure WIFI.

Otherwise, read on if you’re interested in how to configure WIFI by editing files on the SD card so that you can manage headless devices.

Not for Bullseye

This guide applies to Raspberry Pi OS versions released after Bullseye (Bookworm, Trixie)

If you’re on an older Bullseye image, none of this is applicable as it used wpa_supplicant.conf.

How is WIFI configured?

WIFI connections are managed by NetworkManager. NetworkManager looks for .nmconnection files in /etc/NetworkManager/system-connections/ and will try to connect to the “best” in-range connection in this directory (control via autoconnect-priority= when several connections are in-range).

.nmconnection files are in NetworkManager’s keyfile format, so we refer to them as keyfiles from now on.

You can think of the keyfiles as being like keys on a keychain:

Let’s say you want to move a device between a couple of locations. You can drop one keyfile for each site’s SSID and the Pi will connect to whatever is in range
If you have an SSID that is no longer broadcast, you can just delete the keyfile
If the SSID password changes, the keyfile can be updated

So the idea is you’re not configuring your one and only WIFI connection - you’re configuring multiple networks and the “best” one will be selected at runtime.

On a running system the preferred way to manage keyfiles is to use NetworkManager itself, with the nmcli tool or the WIFI settings desktop widget.

Gotcha - WIFI Country

The regulatory domain (country) for WIFI must be set, or WIFI will be disabled. It’s normally set with raspi-config and results in a kernel commandline argument being set in /boot/firmware/cmdline.txt, eg:

cfg80211.ieee80211_regdom=AU

Keyfile (`.nmconnection`) example

Connection for SSID ASIO-x
Path: /etc/NetworkManager/system-connections/ASIO-x.nmconnection
uuid must be a unique UUID, generate with uuidgen command (sudo apt install uuid-runtime)
File must be owned by root:root with 0600 permission
Convention is the SSID should be included in the filename
psk field is your WIFI password in plaintext (hence 0600 permissions)

[connection]
id=ASIO-x
uuid=f3e63685-2f34-4c9c-b781-4506eebbe86b
type=wifi
interface-name=wlan0

[wifi]
mode=infrastructure
ssid=ASIO-x

[wifi-security]
key-mgmt=wpa-psk
psk=topsecret123

[ipv4]
method=auto

[ipv6]
addr-gen-mode=default
method=auto

[proxy]

SD card walkthrough

Raspberry Pi OS stores files on SD cards in an ext4 partition. If you have a Linux machine or another Raspberry Pi with an extra card reader, you’re good to go. Windows/Mac users will need additional software to be able to read ext4.

Configuring WIFI connections is as simple as editing files:

Shutdown the Pi and remove SD card
Mount SD card. On Linux it will end up mounted somewhere like /media/geoff/rootfs/
Edit the files under (eg) /media/geoff/rootfs/etc/NetworkManager/system-connections:
- Need to edit files with sudo as they are root owned
- Make sure uuid is unique
- (shortcut) copy and adjust existing files for new connections
- Make sure permissions are root:root, 0600 (check this with ls -l before proceeding)
Unmount and remove SD card, put in the Pi and reboot - you should be online in a couple of minutes

System still running? Planning moving to a new Access Point? Then use `nmcli`

If your not locked out of your system at the moment and are planning on switching WIFI access points, you can just add the new one with nmcli while you still have access.

Example - adding an out-of-range WIFI:

nmcli connection add type wifi ifname wlan0 con-name theSSID ssid "theSSID"
nmcli connection modify theSSID wifi-sec.key-mgmt wpa-psk
nmcli connection modify theSSID wifi-sec.psk "password123"
nmcli connection modify theSSID connection.autoconnect yes

If it worked, you will see the new connection listed in NetworkManager:

# nmcli connection show
NAME                  UUID                                  TYPE      DEVICE 
netplan-wlan0-ASIO-u  6fbd4250-1205-3a84-8c29-6096c50f9538  wifi      wlan0  
lo                    c83b8865-52cd-44d2-bce1-df4ea16bdd3f  loopback  lo     
theSSID               87e14c2a-0372-4484-a41a-f2de6afd079e  wifi      --     
netplan-eth0          75a1216a-9d1a-30cd-8aca-ace5526ec021  ethernet  --   

geoffwilliams@home:~$