Raspberry Pi Zero Headless setup over USB.

1138 views ssh raspberrypi

by CPunch

The Raspberry Pi Zero is a tiny single board computer with 512MB of ram and a 1GHz single core CPU. While this isn't the fastest single board computer by any means, it's tiny form factor let you build some amazing projects with it! Today I'll be showing you how you can set up your Pi Zero so you can SSH into it over USB. To achieve this we're going to emulate an Ethernet interface over USB, this is supported out of the box for Raspbian, which is really cool! I know blogs about this already exist, however they really kind of just say "do this" and not the why and what it actually does. So, hopefully you learn something!

Step 1. Setup

To get started make sure you have the following:

  • Raspberry Pi Zero or Raspberry Pi Zero W
  • Pi Zero USB Case or you could just use a standard USB cable with data pins!
  • MicroSD card (I recommend at least 8gb)

You'll also need a way to be able to flash the MicroSD card. No matter your platform, I recommend using Etcher to flash the MicroSD, it's a FOSS based on electron that lets you easily and quickly flash storage devices.

First, you're going to need the latest version of Raspbian. At the time of writing this, the latest was Raspbian Buster. You can check and download here.

Make sure you get the Lite image! This will save more room for your project!

After downloading it, extract it, put your MicroSD card into your computer, (no need to format it) open it with Etcher and click 'Flash!' This can take a while so go ahead and make yourself some coffee. :)

Step 2: Enabling SSH

Once that finishes, we're going to have to edit some files on the root of our MicroSD. Everything we're going to be editing is in the volume with the 'boot' label name. First, create a file named 'ssh' on the root of the MicroSD. This will enabled SSH without us having to actually boot the pi up and enable it manually. With SSH you can get a remote terminal, and even send files to your pi zero!

On Windows:

  1. Open Notepad
  2. File->Save As...
  3. In the Save as Type dropdown, click 'All Files'
  4. Name the file 'ssh' with NO extension

On *Unix systems:

  1. Open a terminal
  2. cd to root of MicroSD
  3. Run 'touch ssh'

Step 3: Modify config.txt

Alright, now that we have ssh enabled, we want our Pi Zero to talk to our computer over it's USB interface and act like an Ethernet adapter, to do that we will need to modify some files.

  • Open config.txt on the root of your MicroSD
  • Add this to the bottom of the file
  • Save and quit

dwc2 is a service that enables the USB host service. This lets our Pi Zero act like a USB device! There are tons of super super cool projects just with this, but for now we'll only be using this to setup a fake Ethernet adapter.

Step 4: Modify cmdline.txt

Now we have to modify cmdline.txt, this will setup the Ethernet USB services at boot.

  • Open cmdline.txt at the root of your MicroSD
  • right after 'rootwait' add a space and put
  • in the end, the file should look something like:
dwc_otg.lpm_enable=0 console=serial0,115200 console=tty1 root=PARTUUID=17869b7d-02 rootfstype=ext4 elevator=deadline fsck.repair=yes rootwait modules-load=dwc2,g_ether quiet init=/usr/lib/raspi-config/init_resize.sh
  • Its okay if you have different options. Just make sure 'modules-load=dwc2,g_ether' is after rootwait.

g_ether is what emulates an Ethernet adapter. This will let us connect to our Pi over USB!

Step 5: Install an ssh client (Windows Only)

Now that you've setup your distro, you're still going to need to be able to actually SSH into it. Most *Unix distros provide a ssh client by default and can be used by opening a terminal and typing 'ssh [user]@[ip]', however since you're using Windows, you're going to need an SSH client. PuTTY is a very nice SSH client with a built-in terminal emulator.

Step 6: Try it out!

Now, put the MicroSD into the Pi Zero and plug it into your computer. It will start booting. Once the LED stops flashing it's done booting (It might reboot because of FS resizing)

[ SSH example on pop-os, an ubuntu based distro ]

On Windows:

  • Open PuTTY
  • Connect to raspberrypi.local
  • The user by default is pi
  • the password by default is 'raspberry' <-- MAKE SURE YOU CHANGE THIS WITH "PASSWD"
  • You can now use "sudo raspi-config" to setup your wifi if you have the zero w

On *Unix:

  • Open terminal
  • type:
ssh [email protected]
  • it might ask to accept the key fingerprint, type 'yes'
  • The password is 'raspberry' <-- MAKE SURE YOU CHANGE THIS WITH "PASSWD"
  • You can now use "sudo raspi-config" to setup your wifi if you have the zero w


If you're on an Ubuntu-based distro and keep getting a 'raspberrypi.local: hostname not found' error, go to your wired internet settings and make sure both IPv4 and IPv6 have 'Link-Local Only' checked, like so:

(This might also apply to Windows and MacOS as well, but I didn't have access to a windows machine to test this at the time of writing this.)

Congrats! You've just successfully setup your Pi Zero to be used over USB! Have fun with your project, and I hope you've learned something new!

Aug 28, 2019 by CPunch
May 10, 2020 by CPunch

Thanks! I guess I may have been a little confusing with my word choice. I meant that the command to change the password was "passwd."

Apr 29, 2020 by test

Was wondering; why do you suggest to change the password from "raspberry" to "passwd" in specific? Perhaps you should say to change it to the password of your choice. Otherwise, great tutorial.