How to Install Docker on a Raspberry Pi 5

In this How to install and use Docker on Raspberry Pi 5 guide I will walk you through the process I use to get a fresh Raspberry Pi OS image ready for docker workloads. These are my notes and should be considered a living document that may get updated as needed throughout the lifecycle of Raspberry Pi OS (Bookworm).

Prerequisites

This article assumes you have a “Bookworm” based Raspberry Pi 5 running and updated with the latest patches. It should be a fresh install of Raspberry Pi OS with no additional packages installed (or at least no packages related to docker)

This article will also help you install the official docker code. It will also enable buildx and compose. Lastly, I will show you how to alias the older “docker-compose” command to the newer “docker compose” command.

Step 1 – Configure APT package manager

We first need to add all official repos to our machine so that APT doesn’t grab the unofficial packages in the standard Debian repos.

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Step 2 – Install official Docker packages

Next we use apt to install the new packages.

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Step 3 – Add user permissions for Docker

By default, only the root can run docker commands. I generally like to run docker commands from my standard user account. So this snippet will add your user account to the docker group.

sudo usermod -aG docker ${USER}

Before you can use docker, you need to log out and back in. Then you can run this to check that it works.

docker ps

You are ready to go as long as you don’t get an error!

Step 4 – Compose backward compatibility

The version of docker we just installed includes “docker compose”, but most articles and how-to guides out on the net still leverage the older “docker-compose” command. The easiest thing to do is to create a shim so that you can run either.

This next snippet will create a script that catches and converts a docker-compose command into a docker compose command.

sudo touch /usr/bin/docker-compose
echo 'docker compose --compatibility "$@"' | sudo tee /usr/bin/docker-compose
sudo chmod +x /usr/bin/docker-compose

A note on docker build – The docker build command is automatically aliased and will convert the command to buildx as needed. So no need to worry about anything there.

Summary

The procedure above is my standard process to prepare a Raspberry Pi for docker workloads. It may not be complete for all use cases, but it should get you started with the latest versions of docker and its companion programs.

Let me know if I missed anything that would be valuable to add to the process!