Headless Setup of a Raspberry Pi with Raspberry Pi OS

Last updated: 2022/09/04 to fix missing "passwd" parameter & include a detailed guide for wifi setup. Pawel Dube

Download the Raspberry Pi OS

Go to the official Raspberry Pi OS site with a web browser and download the appropriate image. For a headless setup, take "Raspberry Pi OS Lite".

You can also get the link and download from the terminal:

wget [your link]

Decrompress the image:

unxz [the file name]

Flash the image from the terminal:

Insert the target SD card and determine the target device name:


Your target is named /dev/sdx, while x needs to be replaced by the proper letter. CAUTION: this step will destroy your data on this drive. Make sure you have the correct device letter!

sudo dd bs=4M if=[your image filename goes here] of=/dev/sdx status=progress oflag=sync

Make sure there is no unwritten buffer:


Preparations for a headless setup

Mount the boot partition on the sd card. The easiest way is to open it with the file manager, e.g. nautilus. Continue on the console:

Go to the /boot partition, usually this way:

cd /media/[your user name]/boot

make the empty file 'ssh' to indicate to enable ssh on 1st boot:

sudo touch ssh

generate credentials for the standard 'pi' user (we need the 'pi' user, because he has the right groups and permissions pre-set):

echo 'raspberry' | openssl passwd -6 -stdin

The output will look like: $6$RTI2cmwQZ8RKDIsn$DAXHWGgBgF.LDi5fvOoQyh5n7y5KFYRr6FKToomvyx8Tb/efXEUNbQ7t2h2OQIQBM3NJpEdW.6wHF0iQXeKHr , this is the hash of the password 'raspberry'.

Create the 'userconf.txt' in the /boot directory. The user and password hash are seperated by the ':'. Replace the hash with the one you got from the previous command.

sudo echo 'pi:$6$RTI2cmwQZ8RKDIsn$DAXHWGgBgF.LDi5fvOoQyh5n7y5KFYRr6FKToomvyx8Tb/efXEUNbQ7t2h2OQIQBM3NJpEdW.6wHF0iQXeKHr.' > userconf.txt

Make sure there is no unwritten buffer:


Safely remove the SD card.

Optional: add WiFi credentials

follow this guide at step 3.

In a nutshell:

  1. on the boot partition, create a file named wpa_supplicant.conf.
  2. find out your ISO-3166-1 2-letter-code, e.g. "DE", "US", "EN".
  3. add the following to the wpa_supplicant.conf file and replace the parameters with your values (without the []):
ssid="[WIFI SSID]"

For a comprehensive guide to wpa_supplicant.conf, see here.

Should you need a cheap (available for 1-2€) wifi dongle (2.4 GHz only) that works out of the box on all linux machines I ever tested: ID 148f:7601 Ralink Technology, Corp. MT7601U Wireless Adapter.

1st Boot

Insert the SD card properly into the Raspberry Pi, connect the Raspberry Pi to the power source and watch it boot. The LEDs should flash irregularly during a proper boot which might take up to 1 minute.

While still being on your main machine, find out the local IP adress of the Raspberry Pi:

arp -a

If this fails and you do not see the Raspberry Pi, use:

ip addr

And determine your local IP setup, you should find something like: and use it with nmap:

nmap -sn

This should be conclusive, and the Raspberry Pi should appear with something like "raspberrypi". Take the local IP address to log in:

ssh pi@your.local.IP.address

You will be prompted for the password, enter it ('raspberry').


Now, continue in the ssh session (connected to the Raspberry Pi) you established by the command above.

Customize all things necessary with

sudo raspi-config

Change the user

For safety reasons, remove the pi user. Our first setup with a standard user and a well-known standard password is insecure.

The safest option is to create a new user and abandon the 'pi' user. Just renaming the 'pi' user can break some applications, therefore this is not a good idea, although frequently recommended. Making a new user is better. Log in on your Raspberry Pi with the 'pi' and type


You should get a list of groups the pi user belogs to. It looks like this: pi adm dialout cdrom sudo audio video plugdev games users input render netdev gpio i2c spi

Create a new user, we call him 'bob'. You can chose any other name. Feel free.

sudo adduser bob

You can add some information or leave the fields blank by simply pressing enter on each prompt.

Add the groups to bob. Make sure he at least gets the 'sudo' group. You can use the output from above, but you need to seperate the group names by commas ','.

sudo usermod -a -G adm,dialout,cdrom,sudo,audio,video,plugdev,games,users,input,render,netdev,gpio,i2c,spi bob

Reboot: (yes, a logout could be sufficient, but we want to be sure there are no critical jobs running on the old 'pi' user.)

sudo shutdown -r now

Wait for the Raspberry Pi to reboot and login with the new user 'bob': ssh bob@your.local.IP.address

Delete the user 'pi':

sudo userdel -f pi