What does this generator do? Create a ready-to-use WiFi configuration for your Raspberry Pi headless setup β including hidden networks, multiple WiFi networks with priorities, and optional encrypted passwords.
Which format do you need? That depends on your Raspberry Pi OS β select the matching mode above. Not sure which one you have? Enter cat /etc/os-release in your prompt, it will show e.g. VERSION_CODENAME=bookworm.
Your Configuration
π Step-by-Step: How to use the file
NetworkManager automatically reads this file at startup. Depending on whether your Pi is already running or you are just preparing an SD card, the process is slightly different:
Variant 1 β Pi is already running (via SSH or directly on the device)
- Transfer the downloaded
.nmconnectionfile to your Pi, e.g. viascpto your home directory:scp MyWiFi.nmconnection pi@raspberrypi.local:~/
π‘ Replace
piwith the username you chose during setup (usually in Raspberry Pi Imager) andraspberrypiwith your hostname. Raspberry Pi OS hasnβt had a defaultpiuser since 2022. - Move the file to the correct location on the Pi and set permissions:
sudo mv ~/MyWiFi.nmconnection /etc/NetworkManager/system-connections/ sudo chown root:root /etc/NetworkManager/system-connections/MyWiFi.nmconnection sudo chmod 600 /etc/NetworkManager/system-connections/MyWiFi.nmconnection
β The permissions (
chmod 600) are important β otherwise NetworkManager will ignore the file because the password would be readable by anyone. - Restart NetworkManager so it detects the new connection:
sudo systemctl restart NetworkManager
- Check if it worked:
nmcli connection show nmcli device wifi
Variant 2 β new SD card, Pi not booted yet
The rootfs partition (with the /etc/ folder) is not readable under Windows and macOS. There are two ways:
- The easiest way β Use Raspberry Pi Imager: when flashing, enter the SSID and password in the Customisation step under Wi-Fi; the wireless country code comes from Localisation. The Imager automatically creates the NetworkManager file.
- Under Linux (or with a Linux live USB): Insert SD card, mount
rootfs, copy file to/etc/NetworkManager/system-connections/, set permissions as in Variant 1. - Alternative for Windows/Mac: Boot Pi with LAN cable first, then use Variant 1 via SSH.
For older Raspberry Pi OS versions, it is enough to place the file on the boot partition β it will be automatically imported into the system on the first boot.
Variant 1 β fresh SD card (recommended)
- Flash SD card with Raspberry Pi OS (e.g. using Raspberry Pi Imager)
- Do not eject the SD card after flashing β it will show up as a
boot(orbootfs) drive (the partition that also containsconfig.txt) - Copy the downloaded
wpa_supplicant.conffile directly into this boot partition β not into a subfolder - Optional: place an empty file named
ssh(no extension) next to it, so SSH is automatically active on the first boot - Images from April 2022 onwards no longer ship with a default user. If you didnβt create one in Imager while flashing, also add a file called
userconf.txt. It holds a single line:username:encrypted-password. To generate the encrypted password, runopenssl passwd -6, for example on Linux or in Git Bash on Windows. - Safely eject the SD card, insert it into the Pi and boot
- The Pi moves the file to
/etc/wpa_supplicant/on its own during the first boot and connects to the WiFi
π‘ After a minute or two, a new client should show up in your router, named raspberrypi unless you picked your own hostname. Then connect with ssh yourname@raspberrypi.local, using the user you set up in Imager or in userconf.txt. Only images from before April 2022 still have the default pi user.
Variant 2 β Pi is already running
- Transfer the file to the Pi via
scpor paste the contents directly using an editor:sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
- Save the contents (Ctrl+O, Enter, Ctrl+X) and restart WiFi:
sudo wpa_cli -i wlan0 reconfigure
π€ Still unsure? The most important questions explained
Which OS version do I have?
The fastest way to find out is in the terminal (also via SSH):
cat /etc/os-release
There you will see a line like VERSION_CODENAME=bookworm. This is your codename. Rough orientation:
- Current Raspberry Pi OS (since October 2023): NetworkManager β choose the Current Raspberry Pi OS mode
- Older Raspberry Pi OS (before October 2023): wpa_supplicant β choose the Older Raspberry Pi OS mode
Are you just flashing the SD card? Then: Raspberry Pi Imager 2.x and current images = current Raspberry Pi OS.
What is the country code for?
WiFi frequencies are legally regulated per country β especially in the 5 GHz range. Without a correct country code, 5 GHz WiFi often won’t work at all, or your Pi will illegally transmit on channels that are forbidden in your area. On current Raspberry Pi OS, this field is mandatory, otherwise the Pi refuses to connect to 5 GHz networks. Standard for US is US, for UK it’s GB.
What is a “hidden SSID”?
Some routers do not publicly broadcast their network name (SSID) β the network does not appear in the list. This is called a hidden SSID. For your Pi to connect anyway, it must actively search for it. The checkbox sets the necessary switch (scan_ssid=1 or hidden=true).
π‘ Note: “Hiding” practically does not increase security β modern sniffers will find the network anyway. If you don’t have a hidden SSID: leave the checkbox empty.
Multiple networks and “Priority” β why?
Useful if your Pi runs in different locations β e.g. Home + Workshop + Mobile Hotspot on the go. Enter all networks; the Pi connects to the one currently available.
Priority decides what is preferred when multiple networks are available at the same time. Higher number = preferred. Example:
- Home WiFi: Priority
10 - Mobile Hotspot: Priority
1
If both are in range, the Pi chooses Home. You can leave this field blank if you only use one network.
WPA2, WPA3, Open β which one do I choose?
- WPA2 β the standard. 99% of all home networks run on WPA2. If you don’t know otherwise: choose WPA2.
- WPA3 β newer, more secure variant. Only activate if your router and Pi support it (Pi 4/5 with current OS β). Older Pi models (3B, Zero W) do not support WPA3 reliably β choose WPA2 then.
- Open β only for networks without a password (e.g. guest WiFi, hotel, public WiFi). Requires no input in the password field.
Save password as hash β do I have to do this?
No, it’s optional. If enabled, your WiFi password is converted into a 64-character hex code (PBKDF2 method) before saving. Advantage: the plaintext password is not in the file β useful if you share the wpa_supplicant.conf or upload it to GitHub.
The Pi connects just as reliably with it. Only relevant for wpa_supplicant mode β NetworkManager currently only saves the password as plaintext in its configuration file (protect with file permissions: chmod 600).
How does the file get onto the Pi now?
Variant A β Current Raspberry Pi OS (recommended):
- Insert SD card into PC
- Copy the generated
.nmconnectionfile to/etc/NetworkManager/system-connections/on the rootfs partition (under Windows this partition is not visible β here the Raspberry Pi Imager helps: enter your Wi-Fi directly in the Customisation step while flashing) - On the running Pi: place file in
/etc/NetworkManager/system-connections/, thensudo chmod 600 /etc/NetworkManager/system-connections/*.nmconnectionandsudo chown root:root, afterwardssudo systemctl restart NetworkManager
Variant B β Older Raspberry Pi OS:
- Insert SD card into PC
- Copy the file
wpa_supplicant.confto the boot partition (the partition visible under Windows/Mac, containingconfig.txt) - Optional: put an empty file
sshnext to it to activate SSH. On images from April 2022 onwards, youβll also need auserconf.txtunless you created a user in Imager (see the instructions above). - Insert SD card into Pi, boot β the Pi pulls the config into the system on startup
Password special characters β what works, what doesn’t?
The generator takes care of the correct output (escaping of " and ). Nevertheless, note:
- Umlauts (Γ€, ΓΆ, ΓΌ, Γ) work, but are often a source of typos β better to avoid
- Spaces in the password are allowed
- Minimum length for WPA2/WPA3: 8 characters (the standard dictates this)
π‘ Tip β the easiest way remains the Raspberry Pi Imager: When flashing an SD card you can enter hostname, user, Wi-Fi (SSID + password) and SSH directly in the Customisation step β the Imager writes everything appropriately for your OS. The wireless country code is taken from Localisation. This generator is the right choice if you want to set up WiFi afterwards, configure multiple networks, use hidden SSIDs, or generate the config for future use.
