In this lesson you will learn how to remote control your Raspberry Pi over your local network using Secure Shell (SSH).

A common reason for remote controlling your Pi from another computer (like your laptop or desktop) is that you may be using your Pi solely to control some electronics and therefore not need a keyboard, mouse and monitor, other than for setting it up.

It also can just save on desktop clutter, and the problem of having multiple keyboards and mice all over the place.

Secure Shell (SSH) is a feature of Linux that allows you to effectively open a terminal session on your Raspberry Pi from the command line of your host computer.

Recent versions of Rasbpian do not enable SSH access by default.  You can use an empty boot file or raspi-config, which you first saw back in Lesson 2

Using a blank boot file

For truly headless setups, if you can't ssh into your Pi you can't turn on ssh!

It's a bit of conundrum! But you can easily get around it by using a trick in Raspbian. To do so, we simply create a file called ssh. This file does not exist by default and needs to be created. It can be empty. The system looks for it at boot time and will enable ssh if it is there. It is then deleted. So just create a new file and save it as ssh to the boot folder. If you plug the SD card into your computer, just put that ssh file directly in the SD card director's root directory

Using Raspi-Config

In order to do this, open LX Terminal on your Pi and enter the following command to start Raspi Config:

sudo raspi-config

Scroll down to the “ssh” option, it might be under Interfaces or Advanced (they move it around)

Hit the Enter key and then select “Enable”

A script will run and then you will see the following as confirmation:

You will need to reboot your Pi to make the change permanent

Now switch over to using the computer from which you wish to control the Pi.

If you are using a Mac or Linux PC then open a Terminal. On the Mac, you can find this in the Utilities folder of your Applications folder.

Enter the following command into the Terminal window. That's a lowercase L after the dash!

ssh -l pi

You can also use ssh [email protected]

Note that you will need to replace the IP address above with that of your Pi. You can find this by running the command “sudo ifconfig” from the Terminal.

The option “-l pi' specifies that we want to log into the Pi as the user “pi”. The first time you run the command, you will get a security warning about not being able to verify the identity of the machine, say that you want to continue and enter your password (“raspberry” by default) when prompted.

You will notice that the command prompt will change to indicate that you are now connected to your Pi. Try using the “ls” command to show the contents of the current folder on the Pi.

If you use windows, then you will need to download a free program called “PuTTY” from here:

Having downloaded and installed PuTTY (it's a single file called putty.exe), run the program.

Enter the IP address that you found earlier and click “Open”. This will give you a warning (the first time) and then prompt you for the user (“pi”) and password (“raspberry”).

The ssh window will then be ready for use.

For a good example of how to use ssh to remotely configure a raspberry Pi, take a look at this tutorial:

Try exploring your files system by using 'ls' to list the files in the current directory and 'cd' followed by a directory name to change the current directory.

You can edit files using 'nano' followed by the file name and also install software using the 'apt-get' command, as described in some of the earlier tutorials in this series.

When finished with your ssh session, close the client application/window or simply type in exit into the shell window.


If you encounter a connection reset by peer error when trying to connect to your Pi, there could be a problem with the SSH keys. You can 'reset' the keys with the following commands.

First, remove the old keys:

sudo rm /etc/ssh/ssh_host_*

Then regenerate them

sudo dpkg-reconfigure openssh-server

Then try again!

This guide was first published on Dec 20, 2012. It was last updated on Mar 08, 2024.