How to Install Debian on Raspberry Pi (an illustrated guide)

Debian is one of the four main versions of Linux and has been around since 1993. It forms the basis of Raspberry Pi OS, Ubuntu, and many others. When I first got started in Linux, I tried it out, as it was such a key distribution. However it wasn’t nearly as beginner-friendly as other distributions, so I didn’t spend much time with it. Now that I have a little more experience, and Debian has a Raspberry Pi version available, I will try it again and will share my experience with you.

Installing Debian is as simple as downloading the Raspberry Pi image, flashing it to an SD card, booting the Pi, and configuring it. However, it takes more configuration than many other systems. There is no graphical desktop on the Raspberry Pi Debian image, to begin with, but one can be added.

Read on to discover how to configure and install Debian with a desktop environment!

If you are looking to quickly progress on Raspberry Pi, you can check out my e-book here. It’s a 30-day challenge, where you learn one new thing every day until you become a Raspberry Pi expert. The first third of the book teaches you the basics, but the following chapters include projects you can try on your own.

A Brief History of Debian

Best retro-gaming solution
Download the Pi Glossary!
If you are lost in all these new words and abbreviations, request my free Raspberry Pi glossary here (PDF format)!

Debian had a long history, even before the Raspberry Pi was invented. Founded in 1993 by Ian Murdock, it is one of the early Linux distributions and one that is the basis for many other Linux distributions.  

The Debian name is derived from Ian’s girlfriend at the time, Debra, and his first name, Ian. Debian’s key feature at the time was the Advanced Package Tool which is still used with the APT command in Raspberry Pi OS.

Debian releases are named for characters from the Toy Story movies. The current release of Raspberry Pi OS is named Buster after Andy’s pet dog at the end of the series. The current release of Debian is Bullseye, named after Woody’s horse that appeared in Toy Story 2 (list here).

Much of Debian will be familiar to most Pi users, as it is what Raspbian and now Raspberry Pi OS are based on. It is, however, not ready for novice users out of the box.

Debian itself is used on a lot of servers and other high-security-type installations, and so minimal things are pre-configured.

Can you install Debian on Raspberry Pi?

There is an unofficial release for the Raspberry Pi maintained by one of the Debian developers, Gunnar Wolf. While not officially supported by the Debian project, it is well done and Gunnar explains that it is intended to be a very basic Debian system that is bootable on the Raspberry Pi, and not much else, as we’ll see.

If you download a Debian image for a Windows or Mac computer, you will have choices about installing desktop software and different kinds of installers with several options. On the Raspberry Pi, there is only the minimal install, and you can do what you like with it after that… but you have to know-how.

How to install Debian for your Raspberry Pi

Here are the required steps to install Debian on a Raspberry Pi:

  • Download the Debian image built for the Raspberry Pi.
  • Flash it on a new SD card with Raspberry Pi Imager.
  • Insert it into the Raspberry Pi and start it.

Download the Debian image

The first thing we need to do is download an image from this site for our Raspberry Pi.
You can download it from the official website here.

Here, you’ll find a list of available images and the configurations they have been tested with. I chose the second one which is Bullseye, for the Pi 4 with 4 GB, even though I am using an 8 GB model. There are images for each of the Pi families from the Pi 0 through the 400 and versions for Buster and Bullseye of each. Buster is the previous release, and what the current Raspberry Pi OS is based on, but there aren’t enough differences to matter in these installers. Pick the one that matches your hardware and version choice, and then download the file.

Raspberry Pi Bootcamp
Sale: 10% off today.
Take it to the next level.
I'm here to help you get started on Raspberry Pi.
Learn all the skills you need in the correct order.

Image the SD Card

Once downloaded, we need to write the image to an SD card for booting in the Raspberry Pi. The process is the same as for any other image file you may have done in the past, and either Etcher or Imager is an easy choice to accomplish this.

Download Imager

For our example, we’ll use Raspberry Pi Imager, which is available here.

  • Download the version for the computer you’re using to create the SD card (note, you can do this on a Raspberry Pi if you like).
  • Install the downloaded file and launch the software.
  • Once launched, you’ll be presented with the Imager home window.

    We need to select what we want to install and where we want to install it before we can write the image.
  • Click on Choose OS, and select custom from the bottom of the list.

    This will prompt you to locate the image that you want to write to the SD card.
    Navigate to your Downloads folder (or wherever you saved the Debian image) and select it.
  • Next, pick where you want to write the image to.
  • Once complete, we are ready to write the image.

It won’t take long, as there isn’t a lot of data to write since the image does not contain a graphical desktop interface or software. We’ll install those next!

First Boot

Once the SD card is done verifying, it’s ready to boot. Put the SD card in your Pi’s SD slot and power it up. The first boot takes some time as it has a bit of housekeeping to do, but you will eventually get to a very underwhelming prompt:

Debian GNU/Linux 11 rpi4-20210823 tty1
Rpi4-20210823 login:

Your numbers may be different, but the rpi4-20210823 is the name of the computer for now. We can change that later if desired. The login part is waiting for us to type a user name, and the only one set up is root.

Once you enter root and press return, you’ll get some more info about the distribution and that it comes with absolutely no warranty and then a prompt:


Root is the user who is in complete control of the Linux system and has access to everything, so you need to be careful. On the Raspberry Pi, we have the sudo command that can be used when something needs root access, without actually having to open up the system.

Debian explains on the Raspberry Pi download page that they made this choice on purpose because they expect you to need to access the system and didn’t want to have to track or publish usernames and passwords. We need to be careful with the next few steps.

Advanced Configuration of Debian on Raspberry Pi

Now that we have it booted, we still have some work to do to make it usable on a day-to-day basis.

Activate Wi-Fi

If you have an Ethernet connection, you can skip this step, but otherwise, the first thing we need to do is to establish a network connection with Wi-Fi.

All the files we need are there, but we have to give it details about your Wi-Fi network, as clearly Debian wouldn’t have those to include in the setup.

  • To get there, we use the command:
    nano /etc/network/interfaces.d/wlan0
  • You’ll need to remove the # symbols at the front of the lines starting with allow-hotplug wlan0 (I left the one for inet6).
  • Replace the sample information following wpa-ssid with your Wi-Fi’s network name (SSID).
  • Replace the sample information after wpa-psk with your Wi-Fi password.
  • Once done, you can reboot your system:
    No need for sudo as we’re root. In fact, sudo it’s not available by default.
  • Once that’s complete, and you log back in, you should be able to do:
    apt update

If you have a connection to the internet through your Wi-Fi, it will go through the motions of checking with the network repositories to see what needs to be updated. If your internet connection is not working, you’ll get error messages that they can’t be reached. Go back and check your settings if this happens.

Once you get the update, it’s a good idea to do the apt upgrade command so that you’ll have an up-to-date system before we continue:
apt upgrade

A bit lost in the Linux command line? Check this article first, which will give you the most important commands to remember, and a free cheat sheet you can download to have the commands at your fingertips.

Configure the keyboard

If you need to switch the layout of the keyboard, this can be done with:
dpkg-reconfigure keyboard-configuration

This will ask you first for the type of keyboard you have and then a second screen will ask for the language.

If you make changes, you’ll need to activate them with the command:

Or better still, reboot.

Master your Raspberry Pi in 30 days
Sale: 10% off today.
Download the eBook.
Uncover the secrets of the Raspberry Pi in a 30 days challenge.
Learn useful Linux skills and practice multiples projects.

Add a user

So that we don’t have to continue to log in as the root user, and so that we can log in once we install the graphic desktop, we need to create a user. This can be done with the command:
adduser pi
(or whatever name you’d like to use)

You’ll get a reply that a new user is being added and a group is being created for that user and that a home directory is being created. That’s all normal, and if you think about the home directory on the Raspberry Pi, the user is called pi and it has its own home directory with all your files.

It will then ask for a password and to confirm your chosen password.

Following that, it asks for a Full Name. I recommend that you give it something (even if it’s just Pi again) because that will be the user account that the graphic desktop uses to help you log in. It then asks for several other pieces of information like Room Number, and phone numbers. You can just hit return on those, or fill them out if you like. The last question is “is the information correct?” Press y and you’ll be returned to the prompt.

While we’re here, this is a good time as any to change (or more correctly, add) a root password. Enter the command passwd at the prompt. Since we’re still logged in as the root user, that’s the password we’re changing. It will ask for the new password and then a repeat. Once complete, that password will be set for logging in as well as any other time you need a root password.

Fixing sudo for your user

And here is where we run into another issue with the configuration of the system as it’s originally installed. We added the user (Pi in my case) and during the desktop install, the sudo command was added, but the system needs to know that Pi is allowed to use sudo to execute commands.

Make sure you are root, or switch to it with:
su root

This will switch the user to root, as the Pi user doesn’t have permission to do this yet. You’ll be asked for the root password if you set one in the step above.

At this point, there is a confusing problem with the available commands, but it seems to be temporary. If we just try to use the usermod command, we get a message that it can’t be found.
This is because the root user (which we have switched to) does not have the correct information in the PATH variable for the system.

Instead, type this command:
/sbin/usermod -aG sudo <username>
Replace <username> with the user you created (pi for example).

This will add the user Pi to the sudo group so that it will now have permission to issue sudo commands. You should now be able to switch back to the pi user by using:
su pi
(or your username)

Hopefully, everything will then work normally. If you want to try it out, you can issue any sudo command including:
sudo reboot

Adding the desktop environment

At this point, we have enough information to add the desktop environment, but you’ll have some choices to make here too. Entering the command:

The root prompt will bring up a window with choices of desktop environments you can install. These include several, ranging from lightweight choices like MATE and LXDE to some pretty heavyweight distros like Plasma and Gnome.

Gnome is the default package if you download a full Debian installer for other computers, but since we only have the basics, we have to install one, and we can choose. I have installed Gnome, and it seems to work reasonably well on the Pi 4, even though it’s considered a fairly heavy distro.

LXDE is the one that the Raspberry Pi OS is based on, so it will be most familiar, although it will still look quite different than the classic Pi OS that you’re used to. The nice thing is that you can install more than one, if you have space, and select which one you want to use at startup.

Keep your eye on the installation for a few minutes, as it will pop up and ask what language should be installed. Once you answer that, you can just let it run.

Once installed, a reboot should bring you to the graphic desktop login, and you should see the user name’s Full Name that we entered earlier as a choice. Log in, and you’ll get the desktop screen.

At this point, feel free to explore the desktop environment. You might want to look at all apps, settings and under power, adjust the time before the screen is blanked – 5 minutes is not nearly long enough for my taste.

As you look around, you’ll see many familiar programs and commands, but also a lot of new ones, particularly in settings. Gnome is highly customizable and just about every piece of the user interface can be adjusted to your liking.

Install another desktop

If you’d like to play with another desktop environment, it’s easy to add more on.

  • Open a terminal window and type:
    sudo tasksel
  • You’ll get the same window with choices that you can pick.
  • Pick one or more and wait for the installation to complete.

After the installation completes, you’ll need to restart. On the login screen, you pick the username, and then in the lower-right corner, there’s a settings menu (looks like a gear).
You’ll find listed all of the desktop environments you have available. There is a Gnome classic as well as the Gnome that is the new standard.

LXDE Desktop


Get My Cheat Sheet!
Grab your free PDF file with all the commands you need to know on Raspberry Pi!

Debian is one of the old Linux distributions that has stood the test of time. It is a very relevant distribution because it is the basis of so many other distributions. However, it is difficult to recommend this as anything other than a fun experiment, and it is not for the beginner. If you’re curious and would like to play with Debian, then have fun.

If you’re just getting started and want a new distribution or a different type of desktop environment, I’d suggest using one of the many that are pre-configured for the Pi, such as Ubuntu or Twister. Have fun!

If you have any comment, suggestion or just want to chat with us about this tutorial,
you can post your messages in the community on Patreon. See you there!

Raspberry Pi Resources

Not sure where to start?
Understand everything about the Raspberry Pi, stop searching for help all the time, and finally enjoy completing your projects.
Watch the Raspberry Pi Bootcamp course now

Master your Raspberry Pi in 30 days
Don’t want the basic stuff only? If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiples projects with step-by-step guides.
Download the e-book

VIP Community
If you just want to hang out with me and show your support, you can also join the Patreon community. I share behind-the-scenes content there and give you early access to my content. You’ll also get a shoutout when you join.
More details here

Need help to build something with Python?
Create, understand and improve any Python script for your Raspberry Pi.
Learn the essentials, step-by-step, without losing time understanding useless concepts.
Get the e-book now

You can also find all my recommendations for tools and hardware on this page.

This tutorial doesn't work anymore? Report the issue here, so that I can update it!

Ken Reiss

Ken is a semi-retired computer consultant with a lifelong love of just about anything electronic. He started with the Raspberry Pi just as the Pi 4 was announced and got hooked pretty quickly. He still teaches a couple of courses at one of the local universities, just for fun.

Recent Posts

Master your Raspberry Pi in 30 days

Download this eBook and discover:
1. Secrets from my 20-years Linux experience 2. Many step-by-step projects for your Raspberry Pi 3. How to save time by learning the right way
Master your Raspberry Pi - 10% off