Raspberry Pi Zero W headless setup on macOS

🕒  Posted

Recently I acquired a RaspberryPi Zero W, a few years after I regretted selling my RaspberryPi B board back in 2013. The following is an account of the trials and tribulations I endured to get it connected to the internet!

This setup requires no monitor, or external keyboard, not even the OTG USB cable that I bought because I thought I needed it.


If you’re reading this you’re probably here to learn how to get a rPi Zero W running Raspbian and connected wirelessly to the internet. To do that, there’s a few things you’ll need:

  1. A copy of the Raspbian Jessie Lite image
  2. An 8GB+ MicroSD card (and some way to plug it into your computer in order to flash an image to it)
  3. A micro USB cable (to plug the rPi into your computer temporarily)
  4. A 2.4Ghz wifi access point (the rPi Zero W doesn’t support 5Ghz which I learned the hard way 😞 )

If you have all of these things, great! If not, order all the parts quickly on BuyAPi and continue as if you have them in hand.

Preparing the SD card

I’ve ran these commands on macOS, so your mileage may vary on Windows/Linux. Plug the SD Card into your computer and once it is mounted you’ll want to unmount it from the terminal to flash it.

To unmount the drive and prep it for writing the image, run the following:

sudo df -h # Use the output of this to determine <diskname> in the next command
sudo diskutil unmount /dev/<diskname>

If the previous command completed, you have a drive that you can copy the Raspbian image to!

Writing the image to the SD card

Run the command below to start writing the image to the SD card:

sudo dd bs=1m if=/path/to/raspbian-jessie-lite.img of=/dev/rdisk2
# Where disk2 is the number of the disk from earlier

The command above should only take a few minutes depending on the size of the SD card. After it completes you’ll need to do a few things.

Start by opening your terminal and running touch /Volumes/boot/ssh. The existence of this empty file in the root of the drive will enable SSH on first boot when we connect it with the USB cable.

Next, append dtoverlay=dwc2 to the end of the /Volumes/boot/config.txt file on a new line.

Finally, open /Volumes/boot/cmdline.txt and insert modules-load=dwc2,g_ether after the rootwait entry following the same space-delimited pattern as the rest of the file.

Once you’ve completed the steps outlined above, unmount the drive again from the terminal and plug it into the rPi and connect the power USB cable to the board.

First boot into the OS

Give the rPi about 60s to boot up and then connect the other USB cable from the OTG port to your computer.

Once connected, open System Preferences -> Network and you’ll notice there is a new RNDIS/Ethernet Gadget network adapter added in the list. It will probably show up with a 169... IP address so you’ll need to head to System Preferences -> Sharing now to enable “Internet Sharing” for the RNDIS/Ethernet Gadget adapter.

Make sure you check the correct boxes as illustrated below:

macOS Network Adapters macOS Network Sharing Configuration

Once you have local network access to the rPi, you can ssh in with:

ssh pi@raspberrypi.local

SSH into the RaspberryPi

Once you’re ssh’d into the rPi, you can setup the wifi so that being connected via USB is nolonger required.

In order to get the right configuration for your wifi, run the wpa_passhrase utility with your SSID and it will ask for your password:

wpa_passhrase "SSID HERE"
# You will be prompted to enter your password.
# The utility should generate something like:
#   network={
#   	ssid="SSID"
#   	#psk="PASSWORD"
#   	psk=...
#   }

NOTE: If you have a custom wifi setup that isn’t WPA2-PSK/TKIP encrypted network, you will need to do some research into the config values for wpa_supplicant!

Copy the output of the command above into the /etc/wpa_supplicant.conf file and overwrite whats in the network={...} section.

sudo nano /etc/wpa_supplicant/wpa_supplicant/conf

After pasting the output, save and exit the file. wpa-supplicant should pick up on the changes to the file and connect to the wifi automatically.

You can confirm that your rPi has connected to your wifi by running sudo ifconfig wlan0 on the rPi in your SSH session. In the output, look for inet addr:... which should display and ip address. If this looks correct, then your rPi is connected to your DHCP server/router.

The other option is by checking in the GUI of the router itself in your browser to see if the router issued an IP address to the rPi.

Update the system

Once you’re connected to the wifi, the first thing you should do is update apt-get and upgrade Raspbian as there are undoubtedly some security packages between the image creation and the time you install it on your rPi.

sudo apt-get update -y
sudo apt-get upgrade -y
sudo apt-get dist-upgrade -y

Once you’d completed the above steps, you should now have a functioning RaspberryPi Zero W connected to the internet and ssh’able!

Optional things to do after setup


If you enjoyed this content, please let me know on Twitter!