Skip to main content

🐳 Install Docker & Docker Compose on Raspberry Pi

This guide shows a safe, tested way to install Docker and Docker Compose (Compose v2) on a Raspberry Pi running Raspberry Pi OS / Debian. It includes prerequisites, commands, verification steps and useful post-install tips.

✅ Prerequisites​

  • Raspberry Pi with a supported 64‑bit or 32‑bit OS (Raspberry Pi OS / Debian)
  • Network access (internet)
  • SSH or local terminal with a sudo user
  • Minimum 1–2 GB RAM (more recommended for heavier images)

⚠️ Notes before you start​

  • Do not run commands as root unless necessary — use sudo. Avoid persistent sudo su.
  • A reboot is only required if kernel or low-level packages are updated.
  • This guide installs Docker using the official install script (convenient and maintained by Docker). If you prefer manual repository setup, adapt steps accordingly.

1) Update system packages​

Open a terminal and run:

sudo apt update
sudo apt upgrade -y
sudo apt autoremove -y

Reboot only if the kernel or critical packages were upgraded:

sudo reboot
# Wait for the Pi to come back online, then reconnect via SSH

2) Install required helper packages​

Install HTTPS transport and other helpers (some systems already have these):

sudo apt install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common

Install Docker Engine using Docker's convenience script:

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

Enable Docker to start on boot and check status:

sudo systemctl enable --now docker
sudo systemctl status docker --no-pager

Verify Docker version:

docker --version

Run a quick test container:

sudo docker run --rm hello-world

If the test prints a success message, Docker is installed correctly.

4) Allow your user to run Docker (optional but convenient)​

Add your regular user to the docker group so you can run docker without sudo:

sudo usermod -aG docker $USER

Important: Log out and log back in (or reboot / start a new login shell) for group membership to take effect. After re-login, verify:

docker run --rm hello-world
# (should run without sudo)

If it still fails, you may need to reboot.

5) Install Docker Compose (Compose V2 plugin) — recommended​

Compose V2 is available as the docker compose plugin. Install with apt where available:

sudo apt update
sudo apt install -y docker-compose-plugin

Verify Compose:

docker compose version

Alternative: install the standalone docker-compose binary (legacy / v1) only if you need compatibility with older projects.

6) Common post‑install checks​

  • Docker daemon running:
sudo systemctl status docker
  • List containers:
docker ps -a
  • Show Docker info:
docker info

7) Useful extra tips​

  • To update Docker later:
curl -fsSL https://get.docker.com | sh

or use your package manager if installed from repository.

  • To update Compose plugin:
sudo apt update
sudo apt upgrade -y docker-compose-plugin
  • To remove old Docker versions (if present):
sudo apt remove -y docker docker-engine docker.io containerd runc

  • If using a firewall (ufw), allow needed ports for services you run, not Docker itself. Consider restricting external access or using a reverse proxy for web interfaces.

  • For Raspberry Pi OS 32-bit vs 64-bit: some images require 64-bit. Prefer the 64-bit OS on Pi 4/5 when running heavier containers.

8) Quick troubleshooting​

  • Permission denied when accessing /var/run/docker.sock:

    • Ensure your user is in the docker group and you re-logged in.
    • Avoid changing socket ownership to 777 — prefer group access control.

  • docker command not found after install:

    • Re-login or open a new terminal session.
    • Verify PATH and that the install completed successfully.

  • Problems with containers not starting:

    • Check logs: docker logs <container>
    • Inspect service status: docker compose logs -f (in project directory)

Example: common commands summary​

# Update system
sudo apt update && sudo apt upgrade -y

# Install helpers
sudo apt install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common

# Install Docker
curl -fsSL https://get.docker.com | sh
sudo systemctl enable --now docker

# Optional: allow non-root docker usage
sudo usermod -aG docker $USER

# Install Compose v2 plugin
sudo apt install -y docker-compose-plugin

# Verify
docker --version
docker compose version
docker run --rm hello-world

Docker is now installed on your Raspberry Pi. You can now run containers, use Docker Compose projects, and deploy services like Portainer, OctoPrint, Home Assistant, etc. Remember to secure and backup important data (volumes, configs) for production use.