Run Docker Raspberry Pi

The Raspberry Pi is an excellent choice for a maker board. A lightweight, well supported single-board computer, there's a ton of supported software. Docker, a popular tool for quick creation, deployment, and running of container-based applications is a fantastic choice for developers and system administrators (sysadmins). Dec 12, 2019 Contents. How to Install Docker on Raspberry Pi. Step 1: Update and Upgrade. Step 2: Download the Convenience Script and Install Docker on Raspberry Pi. Step 3: Add a Non-Root User to the Docker Group. Step 4: Check Docker Version and Info. Step 5: Run Hello World Container. Raspberry Pi Docker Images.

For the makers here at Raspberry Valley, we chose the easiest approach: Install via pip. Simply run the following: # Install pip if not available sudo apt update sudo apt install -y python python-pip # Install Docker Compose from pip sudo pip install docker-compose # on some Raspbian flavors, the 'pip install' fails. Sep 30, 2021 Running Docker On Raspberry Pi 2 Run Docker On Raspberry Pi Zero Docker images can support multiple architectures, which means that a singleimage may contain variants for different architectures, and sometimes for differentoperating systems, such as Windows.


This post will show you how to install Docker and Docker-Compose on a clean Raspberry Pi:

  • docker cli is typically used to manage individual containers
  • docker-compose cli on the other hand is used to manage multi-container applications

Full definition of Docker Compose:

Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.

Raspberry Pi OS setup

O/S installation

Refer to the official 📖 Raspberry Pi documentation which goes through all required steps to get your RPi up & running. I’ll quickly summarize the steps which I’ve gone through.

  • Download & install Raspberry Pi Imager
  • Select Raspberry Pi OS (32-bit) Lite if you’ll be running a headless install. Alternatively, use the “Full” version if you want the desktop version.
  • Add an empty ssh file to the root of SD card. This enables SSH on first boot.
  • Connect via SSH using the default credentials:
    • user: pi
    • password: raspberry

Upgrade packages

By now you should’ve succesfully connected to your RPi via SSH. Next up, we’ll update our packages:

Update package list:

Check which packages can be upgraded:

Upgrade installed packages to latest version:

Docker installation

Docker itself provides a so called convenience script which automatically detects your distribution and takes care of all dependencies for you. Before blindly downloading & running it, have a 🕵 look at what’s inside here. These are the steps I used to install Docker:

Download Docker’s install script:


Run it 🚀 and let it work its magic:

We won’t be needing this script anymore, so delete it:

Add non-root user to the Docker group

In order to run Docker commands without adding sudo to all your commands, we’ll add the current user to the docker security group.

This will add the pi user to the dockergroup:

We’ll have to logout and log back in before this will actually work, so type:

Verify Docker install

Show the Docker version information:

Run a test container:

This should output something similar:

Remove the image:

Docker Compose install

Installing docker-compose using the apt package manager will fail as Raspberry Pi’s arm architecture is currently (August 2020) not supported 🤷‍♂.

If you do feel brave and try using apt-get, you’ll most likely end up with the following error when you try running docker-compose:

Use the below pip installation method instead:

Verify Docker Compose install

Running docker-compose version should output something like this:

You can now run & manage Docker containers using Docker and/or Docker Compose 🐋!

Estimated reading time: 5 minutes

Docker images can support multiple architectures, which means that a singleimage may contain variants for different architectures, and sometimes for differentoperating systems, such as Windows.

Linux Hint LLC, email protected 1210 Kelly Park Cir, Morgan Hill, CA 95037email protected 1210 Kelly Park Cir, Morgan Hill, CA 95037.

When running an image with multi-architecture support, docker willautomatically select an image variant which matches your OS and architecture.

  1. Here are 5 things you need to know about using Docker on the Raspberry Pi from Docker Captain Alex Ellis @alexellisuk. If you're new to Docker then visit my Hands-On Docker online workshop: Hands-On Docker labs. Install Docker with one command. Today there is no need to brace yourself for pages of hacks or technical jargon to get Docker onto.
  2. A Raspberry Pi cluster can be used anytime you want to improve performance or availability, and there are many use cases including serving web content, mining cryptocurrency, processing large amounts of data (using tools like hadoop), and much more. This guide will show you how to run a Raspberry Pi cluster using Docker Swarm.

Most of the official images on Docker Hub provide a variety of architectures.For example, the busybox image supports amd64, arm32v5, arm32v6,arm32v7, arm64v8, i386, ppc64le, and s390x. When running this imageon an x86_64 / amd64 machine, the x86_64 variant will be pulled and run.

Docker Desktop provides binfmt_misc multi-architecture support,which means you can run containers for different Linux architecturessuch as arm, mips, ppc64le, and even s390x.

This does not require any special configuration in the container itself as it usesqemu-static from the Docker forMac VM. Because of this, you can run an ARM container, like the arm32v7 or ppc64levariants of the busybox image.

Buildx (Experimental)

Docker is now making it easier than ever to develop containers on, and for Arm servers and devices. Using the standard Docker tooling and processes, you can start to build, push, pull, and run images seamlessly on different compute architectures. Note that you don’t have to make any changes to Dockerfiles or source code to start building for Arm.

Docker introduces a new CLI command called buildx. You can use the buildx command on Docker Desktop for Mac and Windows to build multi-arch images, link them together with a manifest file, and push them all to a registry using a single command. With the included emulation, you can transparently build more than just native images. Buildx accomplishes this by adding new builder instances based on BuildKit, and leveraging Docker Desktop’s technology stack to run non-native binaries.

For more information about the Buildx CLI command, see Buildx.


  1. Download the latest version of Docker Desktop.

  2. Follow the on-screen instructions to complete the installation process. After you have successfully installed Docker Desktop, you will see the Docker icon in your task tray.

  3. Click About Docker Desktop from the Docker menu and ensure you have installed Docker Desktop version (33772) or higher.

Build and run multi-architecture images

Run the command docker buildx ls to list the existing builders. This displays the default builder, which is our old builder.

Create a new builder which gives access to the new multi-architecture features.

Alternatively, run docker buildx create --name mybuilder --use to create a new builder and switch to it using a single command.

Switch to the new builder and inspect it.

Test the workflow to ensure you can build, push, and run multi-architecture images. Create a simple example Dockerfile, build a couple of image variants, and push them to Docker Hub.

Where, username is a valid Docker username.


  • The --platform flag informs buildx to generate Linux images for AMD 64-bit, Arm 64-bit, and Armv7 architectures.
  • The --push flag generates a multi-arch manifest and pushes all the images to Docker Hub.

Inspect the image using imagetools.

The image is now available on Docker Hub with the tag username/demo:latest. You can use this image to run a container on Intel laptops, Amazon EC2 A1 instances, Raspberry Pis, and on other architectures. Docker pulls the correct image for the current architecture, so Raspberry Pis run the 32-bit Arm version and EC2 A1 instances run 64-bit Arm. The SHA tags identify a fully qualified image variant. You can also run images targeted for a different architecture on Docker Desktop.

You can run the images using the SHA tag, and verify the architecture. For example, when you run the following on a macOS:

In the above example, uname -m returns aarch64 and armv7l as expected, even when running the commands on a native macOS developer machine.

mac, Multi-CPU architecture support

Run Docker Raspberry Pi 3

Here are 5 things you need to know about using Docker on the Raspberry Pi from Docker Captain Alex Ellis@alexellisuk

If you're new to Docker then visit my Hands-On Docker online workshop: Hands-On Docker labs

1. Install Docker with one command

Run Docker On Raspberry Pi 3 B+

Today there is no need to brace yourself for pages of hacks or technical jargon to get Docker onto your device. One command does it all (through apt-get behind the scenes) - you can even memorise the command:

On Raspbian enter:

Providing you're running Debian or a derivative you're now good to go. The folks at the Docker project build docker/docker from source through CI which includes quality gates around unit and integration tests.

2. Know your Architecture

The Raspberry Pi hardware architecture is called ARM and differs from the architecture behind your regular PC, laptop or cloud instance.

What does that mean? A binary built for either system will not execute on the other.

The helloworld container will not work on the RPi. I'd suggest starting with my tutorial Get started with Docker on your RPi. It recommends a good set of base images to build what you need - whether that be Go, Node.js, Python, Nginx or something completely different.

The following shortcut will show you the architecture on a Pi or regular Linux machine:

Output from my Raspberry Pi and an Azure cloud instance of Ubuntu

All Pis are compatible with ARMv6 architecture so for simplicity's sake I recommend you build your code through an ARMv6 base image and only pull in official distribution binaries from the likes of Golang, Nodejs, InfluxDB etc where they target that architecture.

What does this mean? It means you can't docker run -d -p 80:80 nginx:latest - read on for the workaround.

3. You can't trust anyone (yet)

Raspberry Pi Docker Install

This may seem like a harsh thing to say - but in a climate where even baby monitors and lightbulbs can be taken over to participate in DDOS attacks we need to get smart.

  • Don't use an image unless it's official

There are no truly official images but resin/rpi-raspbian is used by thousands of devices and curated by resin.io. I would recommend creating all your images from this as a base.

The Docker team are working on a set of semi-official images under the namespace armhf and you will see those images coming into play in the Dockerfile.armhf in the docker/docker repo.

Anil from the Docker Inc. team in Cambridge told me how his team are procuring ARM servers like they were going out of fashion in order to create a build-farm to support ARM devices. That infrastructure will enable autobuild support on the public Docker Hub.

  • Don't run any binaries you that didn't compile yourself

Even if it takes 2 days to compile PhantomJS - it's still way better than relying on a tar.gz provided by someone you know nothing about on the internet.

Docker Security by Adrian Mouat coins the term poison image for an image tainted with malware.

I have provided a set of Dockerfiles on Github for common software such as Node.js, Python, Consul and Nginx:

Github: alexellis/docker-arm

If you want to create a Docker image for software such as Prometheus.io, Node.js or Golang then head over to their download page and locate the official binary package for ARM - then add it into one of the base images we covered above.

If no binary exists then take the time to re-build from source and don't take any risks. Google the build instructions if you run into issues - they can often be found from a 5-minute search.

4. Get physical

The Raspberry Pi excels at interfacing with hardware through it's 40-pin header. You can talk to just about any electrical component directly or through add-on boards - if it's rated for 3.3v/5v that's a good start. Manufacturers like Pimoroni have a wealth of purpose-built sensor and LED boards which mean no trailing wires or complicated code libraries.

Have you seen my IoT demo from Dockercon and Container.Camp yet?

Pre-recorded demo for Dockercon break glass in case of laptop failure.

All the Dockerfiles, Python code and build instructions are publicly available. I couldn't have done any of this without the Pi's support for physical hardware.

  • Container Camp write-up including my IoT demo.

Getting live demonstrations from @alexellisuk at @[email protected]#ctmtechpic.twitter.com/6o1Ju0u5lm

Running Docker On Raspberry Pi 2

— comparethemarkt_tech (@comparemkttech) September 21, 2016

5. Build a super-computer

Building a cluster has never been easier than with the built-in Swarm Mode from Docker 1.12 onwards. Take it from me because I spent weeks rebuilding the Swarm, Consul binaries etc to set up a 28-CPU swarm for Linux User magazine.

Now I type in one command on my manager and another on the workers. What's more the managers can also do useful work, where as in the original swarm mode that was harder to achieve.

See Docker's presentation from Container.Camp right here - it literally takes two commands to begin building a super-computer.

Want a secure @docker cluster? No problem, it's built-in: two commands and you're set. @containercamppic.twitter.com/viZ3CEy47g

— Alex Ellis (@alexellisuk) September 9, 2016

The second most common question I get asked is: can I run a minecraft-super-server with a Pi cluster? The short answer is no and the long answer is yes.

Using Docker On Raspberry Pi Spi

You probably won't be playing a graphics-intensive game at a better FPS rate over your new Pi cluster and it probably won't make loading Chrome any quicker, but it's an invaluable learning tool.

You can can deploy your distributed application at an infrastructure rather than at a specific set of servers. For instance:

Using Docker On Raspberry Pi Configuration

  • Deploy an application on real hardware
  • Simulate network/power failures
  • Code against the Docker remote API
  • Track down bottle-necks and show scaling different services increases throughput (or not)

Where next?

Connect with me on Twitter @alexellisuk to go deeper with Docker, DevOps and containers.

Run Docker Compose On Raspberry Pi

Run Docker On Raspberry Pi Zero

Raspberry Pi Software

There's over 28 Raspberry Pi and Docker tutorials on my blog. Explore them all here - ranging from time lapses to IoT sensor monitoring to learning Golang:

Run Docker Raspberry Pi Configuration

Want to learn the basics of Docker in a hands-on way? Visit or fork my online workshop: Hands-On Docker labs

Most Viewed Posts