Installing Docker on the Raspberry Pi

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 on 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

• Raspberry Pi Case Amazon
• USB Keyboard Amazon
• USB Mouse Amazon
• HDMI Cable Amazon

This tutorial was tested using Raspberry Pi OS (Bookworm) running on the Raspberry Pi 5.

Docker for the Raspberry Pi has support for most versions of Raspberry Pi OS, including Trixie, 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.

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 -yCopy

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 | shCopy

This command will pipe the script directly into the command line. Typically, it’s best not to 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 because it automatically detects and installs everything needed to run Docker on the Raspberry Pi.

Setting up your User for Docker

We need to make a slight adjustment to our user account before we can use Docker without issues.

To help make your experience of using Docker on your Raspberry Pi a bit simpler, there is one little adjustment that we will want to make.

These adjustments will help you better with the Linux permission system and will enable your current user to interact with Docker. By default, only the Docker user and the root user will be able to interact wit the Docker runtime.

1. Once Docker has finished installing on 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 $USERCopy

If 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 changes to our users’ groups, we will have to do one of two things. We can either log out and log back in or just restart the device.

If you are using a terminal-only version of Raspberry Pi OS to run Docker, then you can simply run the command below to log out. Otherwise, you will need to use the desktop interface to log out.

logoutCopy

Alternatively, you can just restart your Raspberry Pi to ensure that the group changes stick. Restarting from the terminal is as simple as running the command below.

sudo rebootCopy

3. Once you have either logged back in or your device has restarted, we can verify that the Docker group has been added successfully by using the following command within the terminal.

This command lists the groups the current user is a member of.

groupsCopy

If everything has worked correctly, you should see “docker” in the list of groups.

pi adm dialout cdrom sudo audio video plugdev games users netdev lpadmin docker gpio i2c spi render input

Testing the Docker Installation on Raspberry Pi

With Docker now set up and running on our Raspberry Pi, we can run a quick test to verify it’s working correctly.

1. The easiest way to verify that Docker is working on our Pi is to download and run a container. Luckily for us, the Docker team provides a container designed for this exact purpose.

Running the command below will download, set up, and run the container called “hello-world“. Since we aren’t specifying a repository, this container will be downloaded from Docker Hub.

docker run hello-worldCopy

2. If you have successfully installed Docker on your Raspberry Pi, you should see a giant message that indicates to you that everything is working as intended.

It also gives you an idea of how Docker operates and the steps required for the image to run on your device.

For example, from this we can see that we pulled the ARM64 image of the “hello-world” container. If you were running this on a 32-bit system, the output would look a little different.

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (arm64v8)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

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 to quickly deploy software to 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 containers within a web interface.

If you have encountered any issues installing Docker, feel free to leave a comment below.

With Docker installed, you might also want to take some time to explore some of our many other Raspberry Pi projects. We also have some Docker-specific tutorials that can be worth exploring.