Sunday, 17 February 2019

How to Install docker on raspbian stretch

As part of one of my recent experiments I wanted to install docker on my raspberry pi. The procedure nowadays seems significantly better than a couple of years ago when I first tried. However, there are always some little details that can be a bit frustrating when following steps.

Although the process to install docker is well described in their website, it's focused on Debian distribution. We all know that Raspbian is based on Debian and therefore most of the instructions for will apply without much trouble.

That said, I will detail the exact steps I followed to get docker installed on my raspberry pi, this procedure was tested on 3B, Zero and Zero W.

First, update the package list, if you haven't done yet after setting up your raspberry pi.

$ sudo apt-get update

Install packages to allow apt to use a repository over HTTPS.

$ sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg2 \

Add Docker’s official GPG key. Note that here the url points to raspbian directory and not to debian as per the original instructions.

curl -fsSL | sudo apt-key add -

The next step recommended didn't work for me.

sudo add-apt-repository \
   "deb [arch=armhf] \
   $(lsb_release -cs) \

It failed with an error similar to this:

Traceback (most recent call last):
File "/usr/bin/add-apt-repository", line 95, in 
  sp = SoftwareProperties(options=options)
File "/usr/lib/python3/dist-packages/softwareproperties/"
, line 109, in __init__
File "/usr/lib/python3/dist-packages/softwareproperties/"
, line 599, in reload_sourceslist
File "/usr/lib/python3/dist-packages/aptsources/", line 89, 
in get_sources (, self.codename))
aptsources.distro.NoDistroTemplateException: Error: could not find a 
distribution template for Raspbian/stretch

Instead, I tried this other way, more explicitly setting up the repository into a new docker.list sources file.

$echo "deb [arch=armhf] $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list

With the new source repository in the list, update the package list again.

$ sudo apt-get update

Now we are in a position to install docker-ce from the repository, in this particular case, I ran into an issue with the latest version, documented in github basically they suggest to go back to 18.06.1 which we can get from the command below as per official docker instructions on how to get a specific version.

$ apt-cache madison docker-ce
docker-ce | 5:18.09.0~3-0~raspbian-stretch | stretch/stable armhf Packages
docker-ce | 18.06.2~ce~3-0~raspbian | stretch/stable armhf Packages
docker-ce | 18.06.1~ce~3-0~raspbian | stretch/stable armhf Packages
docker-ce | 18.06.0~ce~3-0~raspbian | stretch/stable armhf Packages

As of this writing, the version I tried is 18.06.2~ce~3-0~raspbian, which can be installed using the apt-get command.

$ sudo apt-get install docker-ce=18.06.2~ce~3-0~raspbian

Also notice that by using this vesion, there's no need to install docker-ce-cli.

Testing everything is running as expected.

$ sudo docker info
Containers: 0
 Running: 0
 Paused: 0
 Stopped: 0
Images: 1
Server Version: 18.06.2-ce
 --- more data --- 

Run the hello world. Usually we get the command sudo docker run hello-world but that only works on "normal" architectures, in this case, we're using ARMv6/7, but to make it more compatible with all of them, I ran the image from arm32v5/hello-world.

$ sudo docker run arm32v5/hello-world
Unable to find image 'arm32v5/hello-world:latest' locally
latest: Pulling from arm32v5/hello-world
590e13f69e4a: Pull complete 
Digest: sha256:8a6a26a494c03e91381161abe924a39a2ff72de13189edcc2ed1695e6be12a5f
Status: Downloaded newer image for arm32v5/hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:

For more examples and ideas, visit:

And that's all, docker installed up and running on a raspberry pi.


If you'd like to get rid of the sudo command every time you use docker, then you can run the following command found in the official guide as a post-installation step. You don't need to create the group as it's already created by docker installation. It adds your user to the docker group.

$ sudo usermod -aG docker $USER

You need to log out and back in for this change to take effect. After that you'll be able to run all docker commands as a regular user.


  1. Hello Abel,
    thanks for these instructions (that I have followed) but something strange occurs inmy Pi Zero W. After the installation all the processes are up and running (including the docker0 device), but after a reboot containerd service aborts with a core dump.

    Moreover during the installation I received the following errors:

    Setting up aufs-dkms (4.9+20161219-1) ...
    Loading new aufs-4.9+20161219 DKMS files...
    It is likely that 4.14.98+ belongs to a chroot's host
    Building for 3.6-trunk-rpi, 4.14.98+ and 4.14.98-v7+
    Building initial module for 3.6-trunk-rpi
    Error! The dkms.conf for this module includes a BUILD_EXCLUSIVE directive which
    does not match this kernel/arch. This indicates that it should not be built.
    Module build for kernel 4.14.98+ was skipped since the
    kernel headers for this kernel does not seem to be installed.
    Module build for kernel 4.14.98-v7+ was skipped since the
    kernel headers for this kernel does not seem to be installed.
    Setting up linux-headers-3.6-trunk-rpi (3.6.9-1~experimental.1+rpi7) ...
    Examining /etc/kernel/header_postinst.d.
    run-parts: executing /etc/kernel/header_postinst.d/dkms 3.6-trunk-rpi
    Error! The dkms.conf for this module includes a BUILD_EXCLUSIVE directive which
    does not match this kernel/arch. This indicates that it should not be built.

    But, as I already said, just after the installation docker seemed to work properly including the Hello-world test.

    Have you got any suggestion???

    Thanks in advance for your time and support.

    Marco Bagni

    1. Hi Marco, I've tried again since I had to set up another Pi Zero W with docker. This time I didn't manually install containerd package as I don't think we actually need it as such.
      The only unusual thing I found was that after a reboot, docker service is taking a long time to be fully operational, it stays in the state of "activating" for a while until it starts completely.
      About the error messages, I did some research but it seems irrelevant.
      I hope it helps.

  2. Thank you for posting this! Helped out my RPI ZeroW issue tremendously!