Connect To A Raspberry Pi Zero With A USB Cable And SSH

As some of you may know, I have a hoarding problem.  I am hoarding Raspberry Pi microcomputers.  In my personal collection I have one from each generation, making four standard units.  Well, I recently picked up another unit, but this time a Raspberry Pi Zero.  These things are about the size of a nine volt battery, but pack some serious punch.  The problem is they are incredibly rare because they retail for only $5.00.

Unlike the standard Raspberry Pi units, these do not have WiFi, ethernet, or standard sized USB ports.  This changes things when it comes to connecting.  We’re going to take a look at getting set up with one of these Pi Zero IoT devices and be on your way towards some cool hack projects.

Raspberry Pi Zero
Raspberry Pi Zero
Raspberry Pi Zero


Like with the standard Raspberry Pi units, it takes a micro SD card with the same flavors of Linux flashed to it.  You’ll note in my other tutorials, I am using Raspbian, which is a flavor of Debian Linux.  I am using the same for the Raspberry Pi Zero.

Flash the Pi Zero however you see fit.  If you’re using a Mac or Linux computer, you might check out my previous tutorial on the subject.

This is where things get a little different.  Before we get ahead of ourselves, a lot of the material that follows will be from a set of instructions that helped me.  These instructions can be found on GitHub by Andrew Mulholland.

Configuring to Emulate Ethernet Over USB

Our long term goal will be to use SSH over USB.  This means that we have to configure Raspbian to treat the USB port like an ethernet port.  Mount the micro SD card in a computer (not Pi Zero) and open it with Finder, or Windows Explorer, or whatever it is that you use.

The first thing that you want to do is open a file at the root of the mounted drive called config.txt.  In this file you want to add the following line at the very bottom:

The above line will set us up for the next file that we alter.  The next file we alter is cmdline.txt, but it is a bit different.  Parameters in this file are not delimited by new lines or commas, they are delimited by space characters.  In this file we want to add the following:

The above parameter should be added after the rootwait parameter.  Yes the above parameter is a single parameter, meaning don’t add a bunch of space characters to it.  More information on networking over USB on Linux can be found here.

UPDATE 12/11/2016: As pointed out by some readers, the Raspberry Pi Foundation is disabling SSH by default in Raspbian Pixel as a security precaution.  More information on the subject can be found here.  To enable SSH, create a file called ssh and save it to the boot directory of the mounted SD card.  The file can be blank, and it has no extensions.  It should exist at the same location as the other files that were edited.

At this point the micro SD can be inserted into the Pi Zero.

Connecting to the Pi Zero with USB and SSH

To connect to the Raspberry Pi Zero over USB you’ll need Bonjour or similar installed on your host computer.  I’m using a Mac so I was fortunate enough to already be in the clear.  For Windows you should be fine installing iTunes or QuickTime and for Linux the Avahi Daemon.  Many Linux distributions should have it already installed.

With it installed, power on the Pi Zero with the USB data cable.  I made sure to use the port labeled USB, not PWR.  This port allows you to power the Pi Zero and do data transfer.  Once connected, give it some time because it will have to configure some things for the first time.

When you feel the Pi Zero is ready, enter the following from your Mac or Linux Terminal:

If you’re using Windows you’ll have to use PuTTY or similar.  Notice in my SSH command I provided the pi user?  If you’re using Raspbian, it is the only user on a fresh installation.  The password will be raspberry until you change it or add a new user.

You should be connected!  You won’t be able to install anything or run updates because you’re not connected to the internet, but at least you have full headless Linux control.


Raspberry Pi and IoT is awesome.  As a long time Raspberry Pi fanatic, the Pi Zero, if you can get a hold of one, is $5.00 well spent.  You get a fast IoT device at the size of a pack of gum.  Since the hardware doesn’t have WiFi or BLE, we had to configure Raspbian to allow ethernet emulation over USB.  Once we did this we were able to SSH into the Pi Zero as if it was somewhere on our network.  A perfect jumpstart for our Internet of Things adventure.

A video version of this article can be seen below.

Nic Raboy

Nic Raboy is an advocate of modern web and mobile development technologies. He has experience in Java, JavaScript, Golang and a variety of frameworks such as Angular, NativeScript, and Apache Cordova. Nic writes about his development experiences related to making web and mobile development easier to understand.

  • Frank Weiss

    It doesn’t work for me. Mac OS 10.11.5 El Capitan. But looks like Bonjour isn’t hearing anything from the Zero. Neither raspberrypi nor respberrypi.local hotsnames are being resolved on the Mac.

    • I too am using El Capitan.

      Are you sure you’re using the data port and not the power port? Do you have any other Raspberry Pi units on your network sharing the same host name? Are you using Raspbian? Are you sure you flashed the micro SD card correctly and edited the files correctly?

      I’ve done this on two Pi Zero units and didn’t run into trouble.

      Let me know and we’ll try to figure it out together.


      • Frank Weiss

        I’ve double checked all the issues you mentioned. In the meantime, I’ve tracked the problem down to possibly a lack of a RNDIS driver on the mac side. In System Report, no USB shows up when I connect the Zero, however a wifi dongle and Android phone do show up as USB devices when connected. In the network panel, there’s supposed to be a RNDIS device, correct? That’s what the Adafruit page describes: Thanks for your help.

        • I recently had an incident with my Pi Zero so I haven’t been able to check for you, but yea it sounds right.

  • andrew

    not working for me, trying to connect the zero to a rpi3. How do I go about debugging the connection? Thanks

    edit: Changed rpi3 hostname already and plugged into usb

    • I’m not sure what you’re trying to do. Can you give me more information?

      • andrew

        Trying to connect a raspberry pi 3 to a pi zero through usb, so I can SSH into it. Error I get is name or service not known.

        • So you’re trying to SSH into the Pi 3, then from the Pi 3 connection SSH into the Pi Zero? Like I said I need more information in order to help you.

          • andrew

            sorry I only have a raspberry pi 3 and no windows pc or mac. I am wanting to talk to my zero through SSH with my pi3. It would save me buying an hub, so I could use a keyboard and mouse at the same time also the keyboard settings default back to english everytime i un plug it which is annoying lol.

          • Are you using Raspbian? Are you sure your Pi 3 is running Bonjour? If you aren’t using a PC or Mac, how did you edit the SD card of the Pi Zero?

    • malvcr


      I have been trying to put some hardware devices on the RPI3 and just noticed this option, so i gave it a try. And it works as a charm. So, now I can put some devices on the RPI3 and other devices on a RPIZ connected through a USB cable (very nice solution indeed).

      What I could suppose for the people that can’t make this to work is that maybe they are using the wrong USB cable. Because of previous bad experiences with other devices (not Raspberry Pi), I acquired some ANKER data cables that I know can transport electricity AND data. So I made my test with the ANKER cable and everything worked as expected (I am 100% that some USB Belkin cables I have won’t work).

      In both machines, the RPI3 and the RPIZ appeared a new networking device, the usb0 with some 169.254.X.Y weird addresses. As I am working with Jessie Lite, I modified both ip addresses adding static ones in both machines, and now I have two linked machines, where one is for the private usage of the other one, and both sharing the power (even the RPI3 has a SSD disk directly connected to another USB port).

      There is something must be taken into consideration. When using the Zero usb port for networking, won’t be possible to use USB on the Zero for any other purpose, so all the USB possible extra capacity will be lost (could give a try later with USB hubs, but connected on the zero, not on the RPI3). If you can live with that, this seems to be an excellent option to resolve interesting problems using a slave ARM machine.

  • Lisa

    I’m having issues with my rpi zero. After I had done sudo raspi-config on my new rpi0, I followed your directions to edit the files. I’m on Ubuntu 14.04 (with avahi daemon installed), edited through terminal and gedit. I checked my work when I plugged in my rpi0 to a monitor and read the config/cmdline files to be as the directions. Then I plugged into my laptop with USB as power, tried “ssh [email protected]” (had changed raspberrypi to apple), and it says “Name or service not known”. Avahi daemon says it’s running on PID 842, whatever that means. what’s the issue?

    • I may be a bit confused with your scenario, so bare with me for a minute.

      You said you ran raspi-config on the new Pi Zero. Does this mean you already connected to the Pi Zero via SSH once before? This question applies to how you changed the hostname as well.

      When I setup my Pi Zero, I flashed the SD card and immediately went through the steps that I listed. I hadn’t changed the hostname, I hadn’t ran the configuration scripts. Just flashed, altered the files, powered the device on via the data USB port, then tried to SSH via my Mac.

      It does take a bit of time for the Pi Zero to finish booting. Maybe a minute or so. You sure you gave it enough time?

      Happen to have any other Raspberry Pi that are not the Pi Zero? Maybe try to SSH into them from your Ubuntu machine while they are connected to the network (not USB). It would help us rule out the point of failure if you do have a standard Pi. I’ve only ever tried from my Mac, but I can use the ‘.local’ method for any of my Pis, standard or Zero.

      Let me know.


      • workless

        I think he means ‘bear’ with you.

  • vincent courson

    Hello, i followed yours steps but i can’t connect to my pi0 :/

    Config: pi0 connected to the ethernet Hub through a adapter USB/ETH (RASBIAN_FULL)
    My PC is connected to the hub to through ETH (Ubuntu 14 LTS in live)
    When I want to connect on my pi0 with ssh connection, I need a password.. so i have tried:
    pi / raspberry / raspberrypi / 123456789 (after changing)
    The same sentences appears: Permission denied. Please try again.
    after 3 failures: Permission denied. (publickey,password)

    Can you help me please?

    Best regards

  • Rob

    Nic, It works great – but I wanted to take it a step further and configure the interface so I can access the outside world.

    I thought if I’d do the following, I’d configure the interface…

    edit /etc/network/interfaces and add

    and then

    alas, no dice.

    Have you had any luck configuring the interface so that the routing and dns to the outside world works?

  • Abraxas

    It doesn’t work to me! Why!!!!? Please help!!!

    • “It doesn’t work” is not a bug nor is it anything I can help you with. Why don’t you explain what isn’t working, what you’ve tried, and what your setup is. With more details I’d be happy to help you, but can’t as is.


      • Abraxas

        Hi Nic, Thank for that hiper-flash reply. I just shouted help to see if the thread was still alive. I have two raspberry zero one with a dated version of Raspian and the another with the last one, in my pc I have UBUNTU 15.10, with putty installed. I followed very carefully your instructions but it doesn’t work in neither rasp with nor any OS. It’s always throwing “ssh: Could not resolve hostname raspberrypi.local: Name or service not known”. I read that some USB cable make troubles, so I used different of those. I think the problem could be something with my UBUNTU. Could you give me a clue how to discard any problem relative with a malfunction of Ubuntu? Thank a lot for any help.

        • I’m not sure why you’re using PuTTY with Ubuntu as OpenSSH is much better and is native to Linux operating systems. So yes, PuTTY could be the issue. If you’re not using a charge and sync cable, but are using just a charge cable that also could be the issue. Check the cable and make sure you’re using the data port, not the power port on the Pi Zero.

          You might also confirm your text editor is not adding special characters, line returns, etc as well. The files you edit are very strict in what goes in them.

  • Daniyal Ahmed
  • muhammad haris

    I am trying to do the same for rpi3 with ubuntu mate. I have followed your steps but when I plugged in usb on my mac host nothing is detected. Any suggestions? My ssh command returns an error that could not resolve hostname

    • So a few things…

      I don’t believe the micro USB port on the RPi3 is a data port, only power.
      You need the serial to USB cable that makes use of the GPIO pins if you wish to use data over USB.
      This is a Pi Zero guide, so RPi3 questions aren’t best asked here.

      I have other tutorials for standard Raspberry Pi devices. You might want to make use of the search features on this site.


  • Aymon Fournier

    ssh: connect to host raspberrypi.local port 22: Connection refused

    • Any more info than that? Are you using the data port? Did you follow the instructions correctly?

      I’ve done this countless times based on my instructions. More information on what you’re doing would be helpful when it comes to troubleshooting.


      • Aymon Fournier

        I used the data port, I’m using Mac. I found a suggestion where I am supposed to share the connection with the Raspberry Pi Zero, and I did, and it didn’t work either

        • What OS did you install? Be very specific.

          • Aymon Fournier


          • Is that the version with Pixel? I heard another report that SSH wasn’t working correctly with Pixel. I’m wondering if it is disabled by default in that version of the OS.

            I’ve been using Jessie Lite.

  • Joey Link

    Pretty sure I followed the instructions correctly. Trying to ssh into it I get this: Could not resolve hostname raspberrypi.local: nodename nor servname provided, or not known

    Using a Mac by the way

    • Are you using a data cable? Most of the cheapy cables on Amazon are charge only. Another reader had that issue which is why I ask.


      • Joey Link

        Alright I switched data cables. Now I’m getting:

        connect to host raspberrypi.local port 22: Connection refused

        I’m definitely using the data micro-usb port, I changed the config and cmdline files like above. Using Raspbian Jessie with Pixel.

        • I don’t use Pixel, but does that version have SSH enabled by default? Some flavors of Linux don’t have it enabled in a fresh install.

          Make sure that your text editor didn’t add any hidden characters to the config.txt or cmdline.txt files. It is very important that there are no hidden characters, line returns, etc.

          If that doesn’t work, try to re-flash. Maybe your SD flash didn’t go correctly.

          I’ve followed my own guide countless times and haven’t had any issues. I too am using Jessie, but not Pixel.


        • Please see the step by step video I added to this guide.

  • Guest

    I followed the instructions, made sure to use the USB port, and am using a data transfer cable. I have tried both Jessie With Pixel and Jessie Lite, but I’m still getting ssh: connect to host raspberrypi.local port 22: Connection refused. Please help!

    • Ben Papacek

      I had the same problem, and eventually found out ssh is disabled in Jessie by default. To enable it, add an empty file called ‘ssh’ at the root of the boot directory, as explained here:

      • Thanks for sharing this @benpapacek:disqus !

        I think this only applies to Jessie Pixel, not Jessie Lite which is what I was using in the guide. At least this is what the blog post from Raspberry Pi is leading me to believe.

        • Ben Papacek

          It does look like that from the start of the post, but later it says “from now on SSH will be disabled by default on our images”? I tried Jessie Pixel first, then Jessie Lite and got the ‘connection refused’ error both times. Adding the ssh file seemed to help, but it might well have been coincidence. Maybe I got something wrong the first time with Jessie Lite. In any case, thanks a lot for the clear instructions.

          • A week or so ago I tried with Jessie Lite and it seemed to work. Maybe there is a newer release I haven’t tried.

            In any sense, your comment contribution is appreciated. I’ve updated the guide with the info.

      • Guest

        When you say boot directory, do you mean the Raspbian Image inside the MicroSD card?

        • Ben Papacek

          Sorry, I’m not too sure. To clarify, I put the empty file called ‘ssh’ in the same place as config.txt and cmdline.txt, after changing those files as above. This was with Jessie Lite.

          • Guest

            I got ssh working, and was able to login, but now, it says “Connection reset by fe80::2c88:6a6f:579e:749c%bridge100 port 22.” I’m not exaclty sure what that means, and how to fix it. I have tried to wipe the sd card and reflash, as well as install Raspbian Pixel. Alas, it doesn’t work.

          • I created a step by step video tutorial for this to eliminate any concerns. It has been attached to the bottom of the guide.


  • Owen Bramley

    Hi, I recently bought a raspberry pi zero and was trying to set this up. I ran into the dreaded “Connection refused” even though I had setup the pi properly I’m soooo close and really want to get this running. Hoping that it is not something that I need to do with a monitor! Thanks a lot

    Raspberry pi zero
    using mac + default terminal

    • Did you watch the video I made doing it start to finish?

    • Maté Gwozdz

      I am not even getting to the “connection refused”, I have the same raspbian image.

  • workless

    Great video thanks. My situation is a little different so I was hoping someone could confirm if this method will also work for me. I’ve installed my RPi Zero into an LED display with a powered USB Hub which the RPi is using to communicate with two Teensy micro controllers and a USB WiFi. This all works well but I would like to have the ability if possible to connect my MacBook Pro to the spare USB line on the hub and SSH into the RPi that way in case the WiFi route stops working (the RPi is on the back of the display so not easy to access to unplug from the controllers and plug in a dedicated USB without taking the LED display down off the wall). Is this possible? Looking at the video it seems that the changes to the Zero’s configuration mean that it would not be able to switch between using the USB as a normal serial connection and then using it as an ethernet network connection.

    • Maybe look into a USB hub with built in Wifi and Ethernet? When the port is in serial mode, it can’t be used as a standard port.

      • workless

        Thanks Nic. I will look into the hub with ethernet. Didn’t know that existed.

  • Maté Gwozdz

    I went through this 5 times already, last time watching the video and following you on each step.

    I have macOS Sierra and “2017-01-11-raspbian-jessie.img” raspbian image downloaded today from the pi website.
    I waited 10 minutes, the light is green and doesn’t blink every time I ssh [email protected] I just get Could not resolve hostname raspberrypi.local: nodename nor servname provided, or not known. Using data cable, on data port. Any ideas why this is not working? Thank you

    • Do you have a device with a conflicting host name on your network? Are you using a quality data cable? The cheap ones from china never worked for me. Have you added the ssh file?

      Not sure what else to advise since it works fine for me as seen in the video.

    • Maté Gwozdz

      Update, the process worked with the raspbian LITE version, I’ve also switched to 32GB microsd (instead of 4GB one).
      The difference in the whole experience was that when booting LITE version the diode kept blinking, like indicating something is happening. I am wondering, perhaps the full raspbian version simply never booted..? Any ideas how that could be solved?

      • I just tried it with the latest (2017-01-11) build of Raspbian, the standard version, not lite. It worked fine for me. Just to be clear both the current lite and standard versions are working fine.

        This leads me to believe you have maybe a corrupt image.


    • Maté Gwozdz

      If anybody is wondering, makerspot 1.5m cable that comes with power switch IS NOT a data cable. Not very thoughtful of them