Setup WiFi on Raspberry Pi: Step-by-Step

To set up WiFi on a Raspberry Pi, you can use the built-in graphical interface on the desktop, edit a configuration file from the command line, or use the official Raspberry Pi Imager tool before first boot. This guide covers all three methods for current Raspberry Pi OS versions, including headless setups where no monitor or keyboard is attached.

Why WiFi Setup Differs on Raspberry Pi

Unlike a typical laptop, the Raspberry Pi is a single-board computer that often runs without a display. Many users set it up headless, meaning they connect via SSH over the network. This changes how you configure WiFi, because you may not have access to a graphical desktop. Also, the Raspberry Pi uses a specific file named wpa_supplicant.conf for wireless credentials, and the way you edit it depends on whether you are using the desktop or the command line. Newer versions of Raspberry Pi OS also support a dedicated network configuration tool called raspi-config and the nmcli command-line utility.

Method 1: Using the Desktop GUI

If you have a monitor and keyboard connected, the easiest way is to use the graphical interface. Click the network icon in the top-right corner of the taskbar. A list of available wireless networks appears. Select your network, enter the password, and click Connect. The Pi will remember the credentials and reconnect automatically on future boots. This method works on Raspberry Pi OS with desktop, which is the default for most users. If you are using a Pi with a touchscreen, the same steps apply.

Method 2: Using the Command Line (raspi-config)

For those who prefer the terminal or are already connected via Ethernet, run the following command:

Open a terminal window.
Type sudo raspi-config and press Enter.
Select System Options (or Network Options on older versions).
Choose Wireless LAN.
Enter your country code (e.g., US, GB, DE).
Enter your WiFi SSID (network name) and password.
Exit the tool and reboot if prompted.

This method writes the credentials to the system configuration and is reliable for most users. It works on both desktop and Lite (no desktop) versions of Raspberry Pi OS.

Method 3: Headless Setup with Raspberry Pi Imager

If you are setting up a Pi without a monitor, the Raspberry Pi Imager (official tool for writing the OS to an SD card) includes an advanced option to preconfigure WiFi. After selecting the OS and before writing to the SD card, click the gear icon (or press Ctrl+Shift+X) to open advanced settings. You can enable SSH, set a username and password, and enter your WiFi SSID and password. The Imager writes these settings to the SD card, so on first boot the Pi connects automatically. This is the cleanest method for headless setups because you don’t need to edit files manually.

Method 4: Manual Editing of wpa_supplicant.conf

For older versions of Raspberry Pi OS or when you need more control, you can manually edit the wpa_supplicant.conf file. This file is located at /etc/wpa_supplicant/wpa_supplicant.conf. Open it with sudo:

sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

Add the following lines at the end of the file, replacing YourSSID and YourPassword with your actual network credentials:

network={
    ssid="YourSSID"
    psk="YourPassword"
}

Save the file (Ctrl+O, then Enter, then Ctrl+X) and reboot. On newer Raspberry Pi OS versions (Bookworm and later), the system uses NetworkManager instead of wpa_supplicant directly, so this method may not work. In that case, use nmcli instead.

Using nmcli on Raspberry Pi OS Bookworm and Later

Starting with Raspberry Pi OS Bookworm (released in late 2023), the default network manager is NetworkManager. The command-line tool nmcli is the recommended way to configure WiFi. To connect to a network, run:

nmcli dev wifi connect "YourSSID" password "YourPassword"

To see available networks, use nmcli dev wifi list. To disconnect, use nmcli dev disconnect wlan0. This method is more flexible and works with the newer system. If you are using an older version, stick with raspi-config or the manual file edit.

Common Problems and Fixes

WiFi not showing up: Make sure your country code is set correctly. In raspi-config, the country setting affects which WiFi channels are allowed. Also, check that the WiFi antenna is not blocked by the case.
Connection drops: Try disabling power management on the WiFi adapter with sudo iwconfig wlan0 power off (or use sudo iw dev wlan0 set power_save off). Some routers have issues with the Pi’s power-saving mode.
Wrong password error: Double-check that you are entering the correct SSID and password. If your SSID has spaces, enclose it in quotes.
No network after reboot: If you manually edited wpa_supplicant.conf and it didn’t work, you may have a syntax error. Ensure there are no extra spaces and that the file ends with a newline.
Using a 5GHz network: Not all Raspberry Pi models support 5GHz WiFi. The Pi 3B+, 4, and 5 do, but the Pi Zero W and Pi 3B only support 2.4GHz. If your network is 5GHz-only, the Pi won’t see it.

Frequently Asked Questions

How do I find my Raspberry Pi’s IP address after connecting to WiFi?

You can find the IP address by running hostname -I in the terminal. If you are using a headless setup, you can also log into your router’s admin page and look for the device list. Alternatively, use a network scanner app like Fing on your phone.

Can I connect to WiFi without a password?

Yes, for open networks you can omit the psk line in the wpa_supplicant.conf file. However, this is not recommended for security reasons. Most home networks require a password.

Why does my Pi keep forgetting the WiFi password?

This usually happens if the country code is not set correctly. The Pi may be trying to use a channel that is not allowed in your region. Set the country code in raspi-config and reboot. Also, ensure you are using the correct network manager for your OS version.

How do I connect to a hidden WiFi network?

In the wpa_supplicant.conf file, add the line scan_ssid=1 inside the network block. For nmcli, use nmcli dev wifi connect "SSID" password "pass" hidden yes.

Can I use a static IP address instead of DHCP?

Yes, you can set a static IP in the network configuration. With nmcli, use nmcli con mod ipv4.addresses 192.168.1.100/24 ipv4.gateway 192.168.1.1 ipv4.dns "8.8.8.8" ipv4.method manual. This is useful for servers or remote access.

What if my WiFi adapter is not detected?

First, check if the adapter is recognized with lsusb or ifconfig. If not, you may need to install additional drivers. Most official Raspberry Pi USB WiFi adapters work out of the box. For third-party adapters, check the manufacturer’s documentation for Linux drivers.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →