Boot Raspberry Pi with wifi on first boot


You got your Raspberry Pi, but you don't have a keyboard and/or a monitor, and you want to connect the Rapsberry Pi via wifi network (a.k.a. 'headless') on the first boot. so how to configure your SD Card to boot up the Raspberry Pi with wifi-only?

With the Raspberry Pi zero (and zero W) gaining popularity, I found myself helping to answer this kind of questions again and again on Raspberry Pi Stack Exchange, there are tons of tutorials on the Internet teach you how to setup a headless connection AFTER you connecting to the Raspberry Pi via ethernet with a keyboard and a monitor on the first boot to configure the system. However, it is not a lot of well-documented on how to create an SD card to boot up with remote ssh access for wi-fi connectivity. So I summarised my various answers on the Stack Exchange and share with this post.

I will skip the creation of an SD card image as the information is readily available on Raspberry Pi official website.

Step 1 - Enable SSH on boot

By default, SSH access is disabled for security reason as many user often forgot to disabled it when using Raspberry Pi as a web server. We will need to enable the SSH when Raspberry Pi is booted up for the first time. To do that, create a file called ssh (with no file extension) and copy it to the SD card. The content of the file doesn't matter.

Step 2 - Add wifi configuration

Create a file name wpa_supplicant.conf and copy it to SD card, the content of wpa_supplicant.conf looks like this:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev


Replace wifi_ssid and wifi_password with your actual wifi network information. The wpa_supplicant.conf file will get copy to /etc/wpa_supplicant/ directory automatically once the Raspberry Pi is booted up.

Replace the country code with your country's ISO 3166-1 alpha-2 code, if you are not sure about your country's alpha-2 code, you can find out from here.

For Raspbian Stretch release since 2018-03-13:
- WiFi is disabled until wireless regulatory domain is set (Pi 3 B+ only) - The domain can be done through 'Raspberry Pi Configuration' (rc_gui), 'raspi-config' or by setting 'country=' to an appropriate ISO 3166 alpha2 country code in /etc/wpa_supplicant/wpa_supplicant.conf.
- Default wireless regulatory domain is now unset

Step 3 - Identify the Raspberry Pi IP address

Raspbian OS by default create a user name pi and have a default host name of raspberry.local, this allows your to login to your Raspberry Pi using the hostname instead of using IP address. This works for Raspbian but may not be the case for other OS. In case you need to find out the Raspberry Pi's IP address. Put the SD card into the Raspberry Pi and boot it up, wait for a couple of minutes and run linux command arp -n -a form your desktop or notebook computer that is connected on the same network. The command will provide a list of IP addressed that is connected to the network. If the Raspberry Pi has a build-in wifi, it is easy to spot the IP address by looking at MAC address as Raspberry pi MAC address always started as b8:28:xx:xx:xx:xx. If you are using a wifi dongle, the MAC address varies, you can compare the lists before and after turning on the Raspberry Pi to identify IP address belong to the Raspberry Pi. Alternatively, you could find out about the Raspberry Pi from your router's DHCP client list by log into your router.

Step 4 - Login via SSH

Run terminal command from your computer to login to Raspberry Pi like this:

ssh pi@raspberry.local

or in case you are using the IP address:

ssh pi@

Replace with the IP address that you identified in step 3.

That's all. You have successfully boot up your Raspberry Pi at first boot with wifi only, no keyboard, no monitor, and no ethernet cable required.

6 comments by readers

  1. Thanks for this guide, there’s a missing “}” from the wpa_supplicant.conf file that had me stumped for quite a while.


  2. Hello, thank you very much for this tutorial.
    Little update : It seems that on Raspbian Stretch released on November 2018 the default hostname of the raspberry pi is raspberrypi.local, and not raspberry.local.


    1. I just created a new disk image based on 2018-11-13 Raspbian Stretch, and can confirmed that the hostname is still `raspberrypi`, this can be verify either by running `hostname` or `cat /etc/hostname`. The `raspberrypi.local` is an internal domain name when you have avahi daemon installed, which allows you to access you raspberry pi using `raspberrypi.local` instead of IP address.

  3. Hi,
    Thanks for this 🙂
    Loooks like setting the right country in the wpa_supplicant.conf also sets the right keyboard at boot!

  4. is it possible to also setup static IP address in a similar way? i mean, but editing files before the first boot?

Comments are closed.