How to Set up WiFi on Your Raspberry Pi Without a Monitor (Headless)

If you don't have Raspberry Pi OS installed, go ahead and install it. Make sure the SD card with Raspberry Pi OS is in your computer using an SD card slot or SD card USB adapter.

The SD card will mount as a drive/directory on your computer called boot. Open the drive using Finder (Mac) or Explorer (Windows).

In Finder on Mac, you can also select Go > Go to Folder from the menu bar and enter /Volumes/boot.

Open a plaintext editor such as Notepad (Windows) or TextEdit (Mac) and create a new file. Add the following to the file for Raspberry Pi OS, Raspbian Stretch, or Raspbian Buster:

country=US # Your 2-digit country code
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
network={
    ssid="YOUR_NETWORK_NAME"
    psk="YOUR_PASSWORD"
    key_mgmt=WPA-PSK
}

If you're using Raspbian Jessie or older, use this instead:

network={
    ssid="YOUR_NETWORK_NAME"
    psk="YOUR_PASSWORD"
    key_mgmt=WPA-PSK
}

Finally, save the file. If you're using TextEdit on Mac, you'll need to go to Format > Make Plain Text in the menu bar before saving. Make sure the filename is exactly wpa_supplicant.conf (remove .txt if it gets added).

Connecting to unsecured networks

To connect to wireless networks with no password on your Raspberry Pi, use the following:

country=US # Your 2-digit country code
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev # Include this line for Stretch
network={
    ssid="YOUR_NETWORK_NAME"
    key_mgmt=NONE
}

With this file in place, Raspberry Pi OS will automatically move it in /etc/wpa_supplicant/ when the Raspberry Pi is booted.

The next step is to boot the Pi and test, but while the SD card is still in your computer I'll mention this now. If you're going to try to connect via SSH, you may need to enable it first. The process is similar to this one.

Next, put the micro SD card into the Pi, boot it, and your Wi-Fi should be connected!

The wpa_supplicant.conf file should disappear from the SD card's boot directory automatically—so if you don't see it next time, that's normal.

If your Pi hasn't connected to Wi-Fi, try these wpa_supplicant troubleshooting tips:

1. Double-check that the file was written in plaintext, without any special characters.
2. Double-check that the file has disappeared from your boot directory.
3. Connect the Pi to a TV or monitor via HDMI to ensure it is booting normally.
4. If you're using a Raspberry Pi Zero W, make sure you're attempting to connect to a 2.4GHz network (the Zero doesn't support 5G).
5. If you're using a Raspberry Pi Zero, make sure it's a Raspberry Pi Zero W, not a regular Zero (only the W supports Wi-Fi and Bluetooth).

If you'd like to monitor your network performance with your Raspberry Pi, check out guide on setting up a network monitor with a Raspberry Pi.