Raspberry Pi WiFi Setup

This guide covers how to configure WiFi on a Raspberry Pi. The method depends on which version of Raspberry Pi OS you are running — recent versions use NetworkManager, while older versions use wpa_supplicant.

Modern Raspberry Pi OS (Bookworm and newer)

Starting with Raspberry Pi OS Bookworm, released 10 October 2023 and based on Debian 12, the default network stack switched from dhcpcd + wpa_supplicant to NetworkManager. WiFi is now managed via nmcli (or the desktop applet), and editing /etc/wpa_supplicant/wpa_supplicant.conf no longer affects the connection on a default install.

Connect to a WiFi network

sudo nmcli device wifi connect "Your-SSID" password "Your-Password"

Connect to a hidden SSID

sudo nmcli device wifi connect "Your-SSID" password "Your-Password" hidden yes

Set the WiFi country code

The country code is required for 5GHz operation in most regions.

sudo raspi-config nonint do_wifi_country MY

Replace MY with your ISO 3166-1 alpha-2 country code.

List, inspect, and remove connections

nmcli connection show
nmcli device wifi list
sudo nmcli connection delete "Your-SSID"

Headless first-boot setup

On Bookworm and newer, the old trick of dropping a wpa_supplicant.conf onto the boot partition no longer works. Use the Raspberry Pi Imager’s pre-configuration screen instead — click the gear icon (or press Ctrl+Shift+X) before writing the image to set the SSID, password, hostname, SSH, and user account. The Imager writes a firstrun.sh script to the boot partition that runs once on first boot.

Older Raspberry Pi OS (Bullseye and earlier)

For Raspberry Pi OS Bullseye (Debian 11) and earlier — including Buster, Stretch, and Jessie — WiFi is configured via wpa_supplicant.

File location

/etc/wpa_supplicant/wpa_supplicant.conf

Edit with any text editor, e.g. sudo nano /etc/wpa_supplicant/wpa_supplicant.conf.

Basic format

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=MY

network={
    ssid="Your-SSID"
    psk="Your-Password"
}

Replace country=MY with your ISO 3166-1 alpha-2 country code.

Avoid storing the password in plaintext

Use wpa_passphrase to generate a hashed PSK, then replace the plaintext psk= line with the hex output:

wpa_passphrase "Your-SSID" "Your-Password"

Hidden SSID

Add scan_ssid=1 to the network block:

network={
    ssid="Your-Hidden-SSID"
    scan_ssid=1
    psk="Your-Password"
}

Open network (no password)

network={
    ssid="Open-Network"
    key_mgmt=NONE
}

Multiple networks with priority

network={
    ssid="Home"
    psk="home-password"
    priority=10
}

network={
    ssid="Office"
    psk="office-password"
    priority=5
}

The Pi prefers the network with the higher priority when both are in range.

Apply changes without rebooting

sudo wpa_cli -i wlan0 reconfigure

Debug connection issues

wpa_cli -i wlan0 status
journalctl -u wpa_supplicant -b

Headless first-boot setup

On Bullseye and earlier, you can drop a wpa_supplicant.conf file containing the network block above onto the boot partition of a freshly flashed SD card. On first boot, the Pi moves it into /etc/wpa_supplicant/ and connects automatically. See the Raspberry Pi Headless Setup guide for the full walkthrough.