Raspberry Pi

Raspberry Pi Headless Setup

Time to prepare your Raspberry Pi for any project. The 'headless' in the title means we will be strictly using the terminal to setup everything and prepare the Pi to run both headless and in desktop mode.


You have a Rasberry Pi, you have downloaded Raspbian images (standard, light) and you now want to figure out how to get it running. You also don't want to pull out your spare keyboard and screen and want to configure and run everything from your PC (remotely - all you need is a network connection). It turns out you can - and this guide tells you how.

Raspberry Pi Headless setup


  • Hardware check-list. Get the below ready for use.
    • Raspberry Pi (any model)
    • Network cable connected to Raspberry Pi and your local network
    • Blank SD card: size recommendations differ based on the Raspbian version you choose, but 4GB recommended
    • USB power adapter
  • Setup the SD card with a chosen distro. Please check our dedicated guide Setup SD Card for details (choice of system, choice of tooling, a step-by-step setup guide)
  • Insert the freshly created SD card into Raspberry Pi, switch on and wait a bit
  • Locate your new IP address. You will need to note it down for first time connecting to your Raspberry Pi. There are zillions of tools out there to choose from. I suggest to use a simple and portable IP scanner - Softperfect Network Scanner - download here. Choose a portable version or install version as you wish
    • TIP: run the tool 2 times: first instance - scan your network before plugging in the Raspberry Pi, in the second instance scan again after plugging in the Raspberry Pi: you can compare side by side what is the new IP added. Saves tons of time.

IMPORTANT: As of the November 2016 release, Raspbian has the SSH server disabled by default. You will have to enable it manually in raspi-config in the terminal. For headless setups, SSH can be enabled by placing a file named 'ssh', without any extension, onto the boot partition of the SD card. Please do so now, otherwise your SSH connection below will not work!

SSH - Initial Configuration

Now you have your Rasberry Pi running and you know it's IP address. Time to connect first time and setup some basics.

  • First, SSH to your Raspberry Pi. I use MobaXTerm Personal which fulfills all my needs (and then some) but any SSH client will do. You can download it here. Note we have a dedicated recipe for SSH tools and connecting to devices found here: Remote Access to Raspberry Pi.
    • TIP: the default username / password (as of this writing) is pi / raspberry. We'll do something about that a few steps down
    • MobaXTerm has a limit to number of connections in the free version. If you need to exceed it, just run the portable version in multiple instances - unlimited connections is what you get. A good idea is to have a dedicated version for your Pis.
  • Run the Raspberry Pi configuration tool bundled with your distro - raspi-config - to set basic settings. We will revisit later for more sophisticated stuff.
sudo raspi-config
  • Now basically just run the first two choices (expand filesystem and change user password) - we will revisit the rest later as mentioned.

    • Expand the filesystem to fill in the whole space of your SD card
    • Setup a new password for Raspberry Pi (we will aim later to remove pi altogether, but while you configure the basics, be safe from the beginning)
  • Reboot for changes to take effect

  • Time to setup security: we have a whole recipe on the subject - Securing your Pi. Basically you want to setup a new superuser to substitute pi, setup other users if needed for your project, remove pi. There are obviously cases with some distros where pi is needed or you simply don't know how to change and keep the desired application(s) working: if you cannot eliminate this feature, then at least try to setup a reasonably complex password...
  • Finally let us finish the basic section with updating. We have a separate recipe on this activity - Updating the Raspberry Pi, but basically all you need to run is all updates to your system
sudo apt update
sudo apt full-upgrade
sudo rpi-update

SSH - Finalizing Configuration

This section describes remaining configurations which might come in handy. Even now however, your Raspberry Pi is ready to run anything. Some of the sections are purely optional. So for each activity in this section, figure out whether it makes sense for your project or note

  • Go ahead and finish configuring the system using the raspi-config utility. At this point in time it is worth mentioning that it is a good idea to learn the configuration tool. There are settings which you might want for a specific purpose of your device and are not mentioned here. Such as enabling the camera. Go ahead and add them to this list.
sudo raspi-config
  • Choose and configure the following sections in raspi-config

    • Set the hostname in Advanced Options - Hostname: Name your Raspberry Pi to allow easy access to the device from other computers and to setup features like file-sharing in heterogenous networks
    • Set locales and timezone in internationalization options, together with keyboard layout*. You can of course make life simple and set the timezone only, other things follow. And once the device boots and is connected to the internet, it should also pull the correct time
    • Set the Advanced Options - Memory Split based on what you want to do with your device. For running completely headless, 16 Megs of graphics memory should suffice. Otherwise the current setting is probably the best
    • Update the raspi-config tool in Advanced Options - Update
  • You might be asked at this point in time to reboot, do it now, whether asked or not

At this point in time it is safe and possible to access your Raspberry Pi not only via SSH. You can also browse your Raspberry Pi via SFTP (if you have not disabled the FTP server). We have a separate section describing this feature. To install the components, it is enough to run

  • Time to install Samba. We have a full guide to setup all Samba related things in. This will, as a side-effect, enable the hostname to be visible.
sudo apt install samba samba-common-bin

and if you remember your configuration settings, edit the configuration file. As mentioned we have a whole samba recipe elsewhere.

sudo nano /etc/samba/smb.conf

If you need a quick copy-paste job when sharing the pi user folder, just take the configuration from below. But as mentioned, Samba is discussed in detail elsewhere

   comment= Pi Home
   only guest=no
   create mask=0777
   directory mask=0777
  • If you wish to have a static IP address for your device, do it now. I recommend to do this only if you have a very good reason. We have a separate recipe to do this: Static IP on Raspberry Pi.

  • Install additional software. This section is completely yours and is a placeholder to setup stuff you use on a daily basis. I usually consider setting up the following:

    • Setup Midnight Commander: a bit of nostalgia for me probably, I do not use it so often - but my fingers still remember the shortcuts :): sudo apt install mc
    • Setup XRDP: sudo apt install xrdp

I love XRDP and prefer it to VNC server anytime. Probably because I use Windows a lot. However for most of desktops (including Pixel which is latest of this writing) you need to either choose XRDP or VNC Server. One or the other really. The Raspberry Pi site on Pixel describes this very clearly: "Please note that if you already use xrdp to remotely access your Pi, this conflicts with the RealVNC server, so you shouldn’t install both at once. If you’re updating an existing image, don’t run the sudo apt install realvnc-vnc-server line in the instructions below. If you want to use xrdp on a clean image, first uninstall the RealVNC server with sudo apt purge realvnc-vnc-server before installing xrdp. (If the above paragraph means nothing to you, then you probably aren’t using xrdp, so you don’t have to worry about any of it!)".

  • Install Arduino if you intend to do some Arduino development: sudo apt install arduino

Where to Next?

Here is a list of where to go from here (on setting up your Raspberry Pi basic image). It does not cover applications, hardware configurations etc. but purely optional steps on setting up your base image. Those topics are covered in more detail elsewhere.

  • Whether you chose a standard version of Raspbian or a Lite version, there will be software installed you simple don't need. Time to cleanup things and re-claim some space. We have a cleanup section available elsewhere: Raspberry Pi Image Cleanup
  • If you wish to spice up your Raspberry Pi a bit, you can also add a Message of the Day ...
  • Now is maybe the time to backup your image and use it next time as a starting point

Yet more Next steps

Similarly to the above section, you can configure even more features. Here are some tips

  • If you have more Raspberry Pi devices, you can use the image you just created to setup a server side or client side for booting from network (applicable to Raspberry Pi 3 upwards)
  • You can transfer your image to a USB device: that is you boot from USB, but the SD card is still present on models older than Raspberry Pi 3. For 3 upwards you can setup booting from a USB device or USB HDD (without SD card present)


  • If you have setup more users, you might find that some have a different shell. To update to bash for a specific username, do this:
chsh -s /bin/bash <username>
  • As of the November 2016 release, Raspbian has the SSH server disabled by default. You will have to enable it manually. For headless setup, SSH can be enabled by placing a file named ssh, without any extension, onto the boot partition of the SD card.

  • If you have started with a full Raspbian installation on the SD card, you might want to remove the desktop. After all this article is all about headless, right? This will give you roughly 1GB of extra space on your machine. To achieve this, type the following in your terminal session:

sudo apt-get remove gnome-shell
sudo apt-get remove gnome-session
sudo apt-get autoremove