by 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.
Equipment List
Here is a list of the equipment we recommend for this Raspberry Pi Docker tutorial.
Recommended
- Raspberry Pi ( Amazon )
- Micro SD Card ( Amazon )
- Power Supply ( Amazon )
- Ethernet Cable ( Amazon ) or Wi-Fi ( Amazon )
Optional
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 most versions of Raspberry Pi OS, including Bullseye, Buster and more.
Video Tutorial
The short video below will take you through the few steps to installing Docker on the Raspberry Pi. Alternatively, the entire written guide is immediately below the video.
Adblock removing the video? Subscribe to premium for no-ads.
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 upgrade2. 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 | shThis 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 your User for Docker
We need to make a slight adjustment to our user before we can start using Docker without issues.
This is to do with the way that the Linux permission system works with Docker. By default, only the Docker user can interact with Docker but there is a way to work around this.
1. Once Docker has finished installing to your Raspberry 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 docker group.
So, our next step is to add our current user to the docker group by using the usermod command as shown below. By using “$USER” we are inserting the environment variable that stores the current users name.
sudo usermod -aG docker $USERIf we don’t add our 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 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.
logout3. 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.
groupsThis 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-world2. 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.Conclusion
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.
Thanks. Way easier than the stuff on the Docker site.
Easy to follow and informative turtorial. I tested this turtorial 11/08/24 with RPI 4, 4Gb RAM, running 64-bit bookworm version 6.6.31. It worked flawless and installed Docker version 27.1.1. I try installing Mosquitto and Zigbee2MQTT in docker.
It’s installing 32bit docker instead of 64bit, can’t install anything from your other tutorials.. any way to fix this?
Hi Brandon,
That is definitely unusual. Are you certain you are running a 64-bit operating system on your Pi? You can verify this by using the following command.
An alternative would be to manually add the Docker repository to avoid the automation of the script. If you are certain you are running a 64-bit system I can provide a workaround.
Kind regards,
Emmet
I was sure that I installed the 64-bit OS and different commands showed that I had 64-bit installed, But with your command it showed that it was 32-bit. Reinstalled the OS and now shows the correct version
Thank you
Where do i put my docker-compose.yml file? in order to run docker compose up -d ?
Hi Anders,
Technically you can put a compose file whether you want. I like to keep mine organized by creating a directory called “/opt/stacks”, and then within this directory storing a compose file under a folder of the name of the project its for. For example, if we were setting up a compose file for nextcloud I would create a folder at “/opt/stacks/nextcloud” and store the file within that.
Hopefully that answers your question.
Kind regards,
Emmet
Very helpful. Used it twice to setup docker and Portainer. Thank you
It was really helpfull
I hit a wall big time following these instructions: the docker daemon wouldn’t start, producing all sorts of errors like:
The solution was mercifully easy but not immediately obvious, so if anyone else experiences the same from the above, all you need do is reboot:
and all fixed 🙂
Thanks, super helpful installation guide! I appreciate that you put in the part about file permissions. Those are one thing that always seems to trip me up if they’re not spelled out for me.
What ever I try I get “Could not resolve host: get.docker.com”
Help please!! I’m on this problem for 2 days now… 😭
Hi DeanG,
That error would be caused but an issue with tire networking. In particular the DNS you are utilising.
You can try changing the DNS provider your Raspberry pi is using to see if that resolves your problems.
Cheers,
Emmet
is it possible to install docker with an active vpn connection?
Hi Joe,
It definitely should be possible, I can’t see why a VPN connection will break it.
Cheers,
Emmet
on my Raspberry pi 4, I had to do a “sudo rpi-update” before the docker engine would start. Hope this helps someone else…
Thank you so much to Raspnoob for suggesting a firmware update – solved my problems immediately! 🙂
That does surprise me. Did you perform a sudo apt-get update && sudo apt-get dist-upgrade before you attempted to install Docker?