Posted inTechnology

How to Install Docker Compose on a Raspberry Pi

Running self-hosted apps on a Raspberry Pi is a great way to keep a small, low-power machine doing real work. And for anything with more than a single container, Docker Compose is the tool that makes it painless: you describe your whole stack in a docker-compose.yml file and start it with one command.

This guide walks through installing Docker and the Compose plugin on a Raspberry Pi, wiring up your user so you don’t need sudo every time, and running your first Compose project. It works on a Raspberry Pi 3, 4, 5 and the Zero 2 W running Raspberry Pi OS (64-bit), which is the recommended setup.

What is Docker Compose?

Docker Compose is a tool for defining and running multi-container Docker applications. A docker-compose.yml file describes the services you want — a web server, a database, a cache, whatever — and Compose starts them all together, on a shared network, with the right ports and volumes. Instead of juggling a dozen docker run commands, you run docker compose up and get your whole app.

Prerequisites

  • A Raspberry Pi (3 / 4 / 5 / Zero 2 W) with at least 2 GB of RAM.
  • Raspberry Pi OS 64-bit (Bookworm) installed and connected to the internet. The 64-bit image is important — it lets you run arm64 images and the native Compose plugin.
  • Access to the Pi via ssh or the local terminal.

Step 1 — Update the system

Start from a clean, up-to-date base:

sudo apt updatesudo apt upgrade -y

Step 2 — Install Docker Engine

The easiest way to install Docker on a Pi is the official convenience script. It detects your architecture (arm64 or armv7) and installs the Docker Engine plus the Compose V2 plugin in one go:

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

When it finishes, Docker should be installed and running:

sudo systemctl status docker

Step 3 — Verify the Compose plugin

Modern Docker installs the Compose V2 plugin automatically, so the command is the two-word docker compose (no hyphen):

docker compose version

If that prints a version like Docker Compose version v2.x.x, you’re done with installation. If it says docker: 'compose' is not a docker command, install the plugin manually. Create the plugins directory and drop in the binary that matches your architecture:

sudo mkdir -p /usr/local/lib/docker/cli-plugins# arm64 — Raspberry Pi OS 64-bit (Pi 3/4/5, Zero 2 W)curl -SL --output /usr/local/lib/docker/cli-plugins/docker-compose \  https://github.com/docker/compose/releases/latest/download/docker-compose-linux-aarch64# armv7 — 32-bit Raspberry Pi OS# curl -SL --output /usr/local/lib/docker/cli-plugins/docker-compose \#   https://github.com/docker/compose/releases/latest/download/docker-compose-linux-armv7sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose

Then check again with docker compose version.

Step 4 — Run Docker without sudo

By default you need sudo to talk to the Docker daemon. Add your user to the docker group so you don’t have to:

sudo usermod -aG docker $USER

The group change takes effect after you log out and back in (or open a new shell). After that, docker ps works without sudo.

Step 5 — Make Docker start on boot

Enable Docker so it comes up automatically when the Pi boots:

sudo systemctl enable docker

Step 6 — Run your first Compose project

Create a project directory and a docker-compose.yml. Here’s a simple Nginx example:

cd ~/my-appnano docker-compose.yml

Paste this in:

services:  web:    image: nginx:alpine    ports:      - "8080:80"    restart: unless-stopped

Now build and start the stack:

docker compose up -d

The -d flag runs it in the background. Open http://<your-pi-ip>:8080 in a browser and you should see the Nginx welcome page. A few handy commands:

docker compose ps          # see running servicesdocker compose logs -f     # follow the logsdocker compose down        # stop and remove the stack

Troubleshooting

  • Wrong architecture. Check your arch with uname -m (aarch64 or armv7l) and match the Compose plugin binary to it. On the 64-bit OS you’ll see aarch64.
  • docker: command not found right after install. Open a new terminal so the PATH refreshes.
  • Image won’t run. Some images only ship an amd64 build. Pick an image that has an arm64/armv7 variant, or pin the platform explicitly with platform: linux/arm64.
  • Low memory. A Pi has limited RAM. Keep your stack light and consider adding resource limits under deploy.resources.limits in your Compose file.

Wrap up

That’s it — Docker and Docker Compose are installed, your user can run them without sudo, Docker starts on boot, and you’ve launched your first multi-service app. From here, most self-hosted tools (databases, dashboards, media servers, home automation) can be dropped onto the Pi with a single docker-compose.yml.

Views: 4