In this project, we will be showing you how to set up and test Docker on the Raspberry Pi.
Docker is an incredibly powerful tool that provides OS-level virtualization to deliver software packages within containers.
Being in a container means the software cannot access anything that the Docker runtime doesn’t hand to it; this can help with security and resource management.
Docker allows you to deploy your software to devices in an effortless way, as everything is included in the container that the runner downloads.
Best of all, Docker does all of this while maintaining a very low overhead. Having a low overhead allows the software to run on a limited resource machine like the Raspberry Pi.
Below we will walk you through the process of installing Docker to your Raspberry Pi, as well as showing you how to test if it is running correctly.
Here is a list of the equipment we recommend for this Raspberry Pi Docker tutorial.
Raspberry Pi 1, 2, 3 or 4
This tutorial was tested using Raspbian Buster. If you are running an older version of Raspbian, you can use our guide to upgrade to Buster.
Docker for the Raspberry Pi has support for Raspbian Jessie, Stretch, and Buster.
Installing Docker to the Raspberry Pi
Thanks to a nifty install script developed by the Docker team, installing the container software is incredibly simple.
You can even complete the following steps by using an SSH connection to your Raspberry Pi.
1. Our first task is to update all our existing packages before we proceed to install Docker.
We can upgrade all existing packages by running the following two commands on the Raspberry Pi.
sudo apt update sudo apt upgrade
2. With our Raspberry Pi entirely up to date, we can now go ahead and install Docker to the Raspberry Pi.
Luckily for us, Docker has made this process incredibly quick and straightforward by providing a bash script that installs everything for you.
You can download and run the official Docker setup script by running the following command.
curl -sSL https://get.docker.com | sh
This command will pipe the script directly into the command line. Typically it would be best if you didn’t do this; however, Docker is a trusted source.
If you are unsure about running this directly without first inspecting it, you can go directly to get.docker.com to view the script.
This script can take some time to complete as it automatically detects and installs everything it needs to run Docker on the Raspberry Pi.
Setting up the Pi user for Docker
We need to make a slight adjustment to our
pi user before we can start using Docker without issues.
This is to do with the way that the Linux permission system works with Docker.
1. Once Docker has finished installing to the Pi, there are a couple more things we need to do.
For another user to be able to interact with Docker, it needs to be added to the
So our next step is to add our
pi user to the
docker group by using the command below.
sudo usermod -aG docker pi
If we don’t add our
pi user to the group, we won’t be able to interact with Docker without running as the root user.
If you want to learn more about permissions and groups in Linux, check out our file permissions in Linux guide.
2. Since we made some changes to our
pi user, we will now need to log out and log back in for it to take effect.
You can log out by running the following command in the terminal.
3. Once you have logged back in, you can verify that the docker group has been successfully added to your user by running the following command.
This command will list out all the groups that the current user is a part of. If everything worked as it should, the group
docker should be listed here.
Testing the Docker Installation on Raspberry Pi
With Docker now set up on our Raspberry Pi, we should now go ahead and test to make sure it’s working.
1. To test if Docker is working, we are going to go ahead and run the following command on our Pi.
This command will tell Docker to download, setup and run a docker container called “hello-world.
docker run hello-world
2. If you have successfully installed Docker to your Raspberry Pi, you should see a message with the following text in it.
Hello from Docker! This message shows that your installation appears to be working correctly.
You are now safe to start using Docker for your project, such as setting up a Docker swarm with your Raspberry Pi.
Docker containers are a great way of quickly deploying software onto your device.
To make your life easier when managing your Docker Containers, you can also set up Portainer on your Pi. Portainer is a neat piece of software that allows you to create and manage the containers within a web interface.
f you have found any issues with installing Docker, then feel free to drop a comment below.