DEV Community

Cover image for Headless Raspberry Pi Zero W Setup

Posted on • Updated on

Raspberry Pi Zero W Headless Setup Headless Raspberry Pi Zero W Setup

This tutorial was originally posted on my blog.

Raspberry Pi Zero W is an affordable and easy to use development board. Since it has limited CPU and RAM resources you can accelerate the development process using the Raspbian headless mode. No additional monitor or keyboard is required in order to get started.

Burn the Raspbian Lite image

First things first: you should download the Raspbian Lite image from the official download site page. You also have to download the Balena Etcher utility, which can be used to flash the Rasbian Lite image without any hassle. You’re also going to need a micro SD card, (a 4GB one will work just great).

Connect your SD Card to your computer and launch the Etcher, select the Raspbian image, select the SD card and flash it. This step might take a while. When the card is flashed it will automatically get ejected.

Enable Wireless networking

The Raspberry Pi Zero W has a built-in WiFi chip which can connect to your wireless network, provided that you specify the credentials first. To do that, attach your SD card to your computer again. The Etcher has renamed the card to boot. Navigate into the directory using your terminal as cd /Volumes/boot/. You can always use your Finder and navigate to the boot directory. Create a new empty file where network info can be storedtouch wpa_supplicant.conf. Edit the file and enter the credentials for your wireless network:

Enter fullscreen mode Exit fullscreen mode

Usually, this setup is good to go.f you find yourself in trouble though you can take a look at the official documentation regarding the wpa_supplicant settings.

Enable SSH access

Now you should enable SSH access to your board. Assuming that you are already in the /Volumes/boot directory, create an empty ssh file as: touch ssh.

Connect to your board

Now it’s time to boot the Raspberry Pi Zero. Insert the SD card into the Pi Zero W and connect it to a power source; a Micro-USB power cable into the power port will do the trick. Once it powers up it takes some time to boot and connect to the WiFi, usually from 45 to 90 seconds. Using nmap or a network scanner like LanScan you have to obtain the new device connected to your network. The Pi also exposes raspberrypi as a hostname. Using the IP address you can SSH your board as:

~ ssh pi@
Enter fullscreen mode Exit fullscreen mode

Type in the password, which by default is raspberry.
You can also use the hostname to SSH, like this:

~ ssh-keygen -R raspberrypi.local
~ ssh pi@raspberrypi.local
Enter fullscreen mode Exit fullscreen mode

Change your hostname and password

For security reasons it’s better to change the hostname and password. Once connected to the Pi use sudo raspi-config. Change the default password and hostname and write down the new hostname. Once the changes are saved reboot the Pi as sudo shutdown -r now. Assuming that your new hostname is *blueberrypi you can connect to the board using SSH as ssh pi@mypi.local.

Get the updates

Finally, you get the latest updates for the Pi as simply as typing:

~ apt-get update -y
~ apt-get upgrade -y
Enter fullscreen mode Exit fullscreen mode

Final thoughts

Raspberry Pi Zero is affordable and super fun to work with. In the upcoming tutorials I am going to show you how you can control external components using Node.js, how you can build and deploy applications using a continuous delivery pipeline and a lot more. Stay tuned!


  • The wpa_supplicant.conf might require a few additional settings, you can take a look at the official Pi documentation.
  • There are some additional docs about connecting to a board using SSH.

Purchase Raspberry Pi Zero W

You can purchase a Raspberry Pi Zero W board online from Seeed Studio.

Top comments (11)

dclowd9901 profile image
David Drew • Edited

This didn't work for me. The unit would never connect to my network and seemed to act like the hardware was malfunctioning. I had to add some additional config to wpa_supplicant.conf:

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


And on top of that, I had to edit /etc/network/interfaces to add the lines:

auto wlan0
iface wlan0 inet manual
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf

where wlan0 represents the wireless interface.

herecomeslappy profile image

I boot the Pi Zero W but it deletes the ssh file and the wpa_supplicant.conf on boot.

vorillaz profile image

That's pretty weird, maybe the SD card does not persist the data.

derickr profile image
Derick Rethans • Edited

Curiously, mine does the same! But only after booting the PI from it. A normal write, unmount, mount, read, works fine!

Thread Thread
durikon profile image

I was facing the same. This worked for me in wpa_supplicant.conf:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
ssid="WLAN SSID"

I also made sure, the file has unix line endings. Using vim, write the file using ':w ++ff=unix'.

razorpi profile image

Same problem as Lappy and Derick. Do you think I should replace the card? I'm using a ScanDisk that came with the kit.

Thread Thread
hildende profile image
Dennis Hildenbrand

Probably a little late but the documentation says "When the Pi boots, it looks for the ssh file. If it is found, SSH is enabled and the file is deleted.".

It's similar for wpa_supplicant.conf (see documentation) "Put this file in the boot folder, and when the Pi first boots, it will copy that file into the correct location in the Linux root file system and use those settings to start up wireless networking."

garyqess profile image
Gary Quinn

A piece of advice to anyone trying to connect your WiFi network to Rasp Pi Zero W:

I've just been through the process of setting up a Rasp Pi Zero W for WiFi connection.
I tried quite a few versions of wpa_supplicant.conf before I got it working.

Rather than going thru all the details (lots of notes about this on line), I'll just give one suggestion to anyone trying to set it up:
First check that it is connecting to your WiFi network by logging into your WiFi router and checking that the Pi is connected BEFORE you try and use putty. You should see "raspberrypi" in the list of connected devices.
Unless you see this, no point in trying to figure out why putty wasn't working.
The reason I'm saying this is my putty session never connected using "raspberrypi" as the host name as is should have according to many app notes.- I had to use the IP address.

So it's possible several of my earlier versions of wpa_supplicant.conf I may have actually been OK, but I never knew it.
Hope that's of use to someone.

theanachronist profile image

Total beginner - can you further break down/explain "Using nmap or a network scanner like LanScan you have to obtain the new device connected to your network. The Pi also exposes raspberrypi as a hostname."? I am legit trying to follow a CHILDREN'S RASPBERRY PI TUTORIAL, and I can't - so, explain it like I'm even dumber than a toddler... ::eye roll::

vorillaz profile image

Hey, apologies for the late reply.
So, in order to make this work, you shall find the IP address of the board. Once the boards get connected with your WiFi you need to find out its IP address.
The official RPI docs have a well-documented set of instructions:

P.S The is no such thing as a beginner and sometimes when you're digging through uncharted waters things may seem a bit overwhelming, but since you'll get a few bits of information everything will be crystal clear :).

Keep up and let me know if you need any extra help.

whaduu profile image

Thanks for this. I used the additional config info from the thread - worked first time. Had to use sudo for the apt-get commands, but otherwise perfect step-by-step instructions.