How to Install Docker on Raspberry Pi (Step-by-Step)

Introduction

Docker turns your Raspberry Pi into a lightweight server that can run dozens of self-hosted services — from Pi-hole to Nextcloud — all isolated and easy to manage. This guide walks you through installing Docker and Docker Compose on a fresh Raspberry Pi, with every command ready to copy-paste.

Prerequisites

• Raspberry Pi 3B+, 4, or 5 (2 GB RAM minimum, 4 GB recommended)
• Raspberry Pi OS (64-bit Lite recommended for servers)
• SSH access or direct terminal
• Internet connection

Step 1 — Update Your System

Always start with a fresh update:

sudo apt update && sudo apt upgrade -y

Step 2 — Install Docker

Docker provides an official convenience script that handles everything:

curl -fsSL https://get.docker.com | sudo sh

This installs the latest stable Docker Engine. It typically takes 1–2 minutes on a Pi 4.

Step 3 — Add Your User to the Docker Group

By default, Docker requires sudo. Fix that:

sudo usermod -aG docker $USER

Log out and back in (or reboot) for this to take effect:

logout

Step 4 — Verify the Installation

docker --version
docker run hello-world

You should see a "Hello from Docker!" message confirming everything works.

Step 5 — Install Docker Compose

Docker Compose v2 comes as a Docker plugin. Install it:

sudo apt install docker-compose-plugin -y

Verify:

docker compose version

Step 6 — Set Up Portainer (Optional)

Portainer gives you a web UI for managing containers:

docker volume create portainer_data

docker run -d \
  -p 9000:9000 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

Open http://<your-pi-ip>:9000 in your browser to set up Portainer.

Step 7 — Enable Docker on Boot

Docker should auto-start, but verify:

sudo systemctl enable docker
sudo systemctl status docker

Troubleshooting

"permission denied" when running docker commands — You forgot to log out after adding yourself to the docker group. Run newgrp docker or reboot.

Slow image pulls — ARM images are smaller than x86 but some pulls can be slow. Consider using --platform linux/arm64 explicitly.

Out of memory — If the Pi freezes during builds, add a swap file:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Summary

You now have Docker and Docker Compose running on your Raspberry Pi. In the next article, we'll set up a headless Pi so you can manage everything remotely over SSH.