wpa_supplicant.conf & NetworkManager Generator for Raspberry Pi (Headless WiFi)

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

πŸ†• Current Raspberry Pi OS .nmconnection

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)

  1. Transfer the downloaded .nmconnection file to your Pi, e.g. via scp to your home directory:
    scp MyWiFi.nmconnection pi@raspberrypi.local:~/

    πŸ’‘ Replace pi with the username you chose during setup (usually in Raspberry Pi Imager) and raspberrypi with your hostname. Raspberry Pi OS hasn’t had a default pi user since 2022.

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

  3. Restart NetworkManager so it detects the new connection:
    sudo systemctl restart NetworkManager
  4. 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.
πŸ“Ÿ Older Raspberry Pi OS wpa_supplicant.conf

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)

  1. Flash SD card with Raspberry Pi OS (e.g. using Raspberry Pi Imager)
  2. Do not eject the SD card after flashing β€” it will show up as a boot (or bootfs) drive (the partition that also contains config.txt)
  3. Copy the downloaded wpa_supplicant.conf file directly into this boot partition β€” not into a subfolder
  4. Optional: place an empty file named ssh (no extension) next to it, so SSH is automatically active on the first boot
  5. 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, run openssl passwd -6, for example on Linux or in Git Bash on Windows.
  6. Safely eject the SD card, insert it into the Pi and boot
  7. 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

  1. Transfer the file to the Pi via scp or paste the contents directly using an editor:
    sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
  2. 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):

  1. Insert SD card into PC
  2. Copy the generated .nmconnection file 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)
  3. On the running Pi: place file in /etc/NetworkManager/system-connections/, then sudo chmod 600 /etc/NetworkManager/system-connections/*.nmconnection and sudo chown root:root, afterwards sudo systemctl restart NetworkManager

Variant B β€” Older Raspberry Pi OS:

  1. Insert SD card into PC
  2. Copy the file wpa_supplicant.conf to the boot partition (the partition visible under Windows/Mac, containing config.txt)
  3. Optional: put an empty file ssh next to it to activate SSH. On images from April 2022 onwards, you’ll also need a userconf.txt unless you created a user in Imager (see the instructions above).
  4. 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.

Copied!