Installing and Running Docker on a Raspberry Pi?

Docker is a popular containerization platform that allows applications to run in isolated environments called containers. Containers are more lightweight and portable than virtual machines. This makes Docker well-suited for deploying applications on resource-constrained devices like the Raspberry Pi.

Installing and Running Docker on a Raspberry Pi?

Benefits of Running Docker on a Raspberry Pi

There are several benefits to running Docker on a Raspberry Pi:

  • Simplified dependency management: Docker containers include all the dependencies an application needs to run. This eliminates issues with conflicting libraries on the Raspberry Pi OS.
  • Portability: Docker containers can run unchanged on any platform that supports Docker, from a Raspberry Pi to the cloud.
  • Lightweight: Containers share the host system’s Linux kernel and do not require an entire guest OS, allowing more applications to run simultaneously.
  • Reproducibility: Docker containers run from immutable images, ensuring consistency across different deployments.

Overall, Docker lets you get more functionality out of your Raspberry Pi. You can use it to experiment with microservice architectures, deploy web applications, and more.


Before installing Docker on your Raspberry Pi, make sure your system meets these prerequisites:

  • Raspberry Pi Model 2 or newer: Older Raspberry Pi models do not meet Docker’s minimum CPU and RAM requirements. Docker requires a 64-bit ARM CPU with virtualization extensions.
  • Raspberry Pi OS (32 or 64-bit): Other Linux distributions like Ubuntu Server also work but Raspberry Pi OS is recommended for full compatibility.
  • User privileges: To manage Docker, your user needs to be in the docker group or have root privileges. Log in as the pi user or a user with sudo permissions.
  • Network connectivity: The Raspberry Pi needs access to download Docker components and container images over the internet. Connect it to a network with internet connectivity.
  • Adequate storage: Docker containers and images can quickly consume storage space. For light usage, a 16GB+ microSD card is recommended. Expand with an external drive if building larger applications.
  • Updated packages: Before installing Docker, run sudo apt update && sudo apt full-upgrade to update the package repository and installed packages. Reboot after updating.

Installing Docker Engine on Raspberry Pi OS

With the prerequisites met, we can install the Docker Engine on Raspberry Pi OS using the convenience script:

  1. Log in to your Raspberry Pi via SSH or the terminal.
  2. Run the installation script:

curl -sSL | sh

  1. After installation completes, verify Docker installed successfully by checking the version:

docker –version

# Docker version 19.03.8, build afacb8b

2.  As a non-root user, add yourself to the docker group to manage Docker:

sudo user mod -aG docker ${USER}

Log out and back in for the changes to take effect.

3. (Optional) If you want Docker to start automatically at boot, enable the service:

sudo systemctl enable docker.service

sudo systemctl enable containerd.service

Docker Engine is now installed on your Raspberry Pi and ready to use!

Optimizing the Docker Setup

There are a couple areas we can optimize on Raspberry Pi to improve Docker’s performance:

Enable the Docker Cgroup Driver

Cgroups allow Docker to efficiently manage and isolate resources for containers. To enable the cgroupfs driver:

  1. Edit the Docker daemon configuration file:

sudo nano /etc/docker/daemon.json

2. Add the following and save:

  “exec-opts”: [“native.cgroupdriver=cgroupfs”]  

3. Restart Docker for the change to take effect:

sudo systemctl restart docker

This optimizes Docker’s coordination with the host Linux kernel for better resource usage and performance.

Configure Docker to Use a pi-optimized Kernel

Specialized third-party kernels like Squeezelite optimize memory allocation and priority tuning for Docker on ARM devices like the Pi.

To configure Docker to automatically use it:

  1. Download and install the kernel:

curl | tar xz -C /

2. Edit Docker’s systemd drop-in directory:

sudo nano /etc/systemd/system/docker.service.d/override.conf

3. Add the following configuration:


Exec Start=  

Exec Start=/user/bin/dockerd -s squeezelite –exec-opt native.cgroupdriver=cgroupfs

  1. Save changes and restart Docker:

sudo systemctl daemon-reload  

sudo systemctl restart docker

Docker will now automatically leverage Squeezelite’s kernel optimizations whenever containers start.

With setup optimized for the Raspberry Pi hardware, we can now run Docker containers!

Running Docker Containers on a Raspberry Pi

Let’s walk through downloading an image and launching an Nginx web server container to see Docker in action:

Download the Nginx image:

docker pull nginx

List downloaded images to verify (Nginx should now appear):

docker images

Run a new Nginx container:

docker run -d -p 80:80 –name my-nginx nginx

  • -d: Run the container in detached mode
  • -p 80:80: Map port 80 inside container to port 80 on host
  • –name my-nginx: Name the container “my-nginx” Check running containers and inspect your container’s details:

docker ps

docker inspect my-nginx

Access your web server by visiting your Pi’s IP on port 80!

With just three commands we downloaded a container image, started an isolated container, and accessed the running application.

Now let’s clean up:

Stop the container:

docker stop my-nginx

Remove the container:

docker rm my-nginx

Remove the downloaded image:

docker image rm nginx

This gives you a quick template for running any Docker application on a Raspberry Pi!

Key Takeaways Running Docker on a Pi

Here are some key takeaways from this guide on getting Docker running on Raspberry Pi:

  • Use Docker for easier dependency management and more portable applications on a Raspberry Pi.
  • Ensure your Raspberry Pi model, OS, user privileges, network and storage meet the prerequisites.
  • Install Docker Engine using the convenience script, add your user to the docker group, and configure the cgroup driver.
  • Further optimize Docker using a container-optimized kernel like Squeezelite.
  • Pull Docker images, run them as containers detached with port mappings, and manage your deployment.

With Docker containers, even modest Raspberry Pis can now support server workloads. This guide shows how to leverage containers to innovate, experiment and learn with your Pi.


Installing Docker Engine on a Raspberry Pi and running containers opens up new possibilities for innovation and discovery. As you explore Docker and deploy your own containers, keep in mind ways you can continually optimize resource usage for your Pi hardware.

Now that you have Docker running, some ideas to continue your container journey:

  • Deploy web applications like WordPress or Ghost blogs using official images
  • Build IoT apps managed through Visual Studio Code or Docker Compose
  • Experiment with Docker Swarm or Kubernetes to create a Pi cluster
  • Check out Docker’s training site for more tutorials and project ideas

We’ve only scratched the surface of what you can achieve by containerizing your Raspberry Pi apps with Docker. Have fun, stay curious, and as always, happy building!

Frequently Asked Questions

  1. What are system requirements to install Docker on Raspberry Pi?
    The minimum requirements are a 64-bit ARM CPU Raspberry Pi model 2 or newer with virtualization support, Raspberry Pi OS as the operating system, network connectivity, at least 16GB microSD storage, Docker user privileges, and fully updated OS packages.

  2. How do I check the Docker version on Raspberry Pi?
    After installing Docker, verify it is the correct version by running docker –version to check.

  3. Do I have to use Raspberry Pi OS or can I use Ubuntu?
    For guaranteed compatibility use Raspberry Pi OS. Other Ubuntu-based distributions may work but some Docker features may not work properly.

  4. How do I start Docker on boot on Raspberry Pi?
    Run sudo systemctl enable docker. Service and sudo systemctl enable containerd. Service to set Docker to start automatically when you boot your Raspberry Pi.

  5. What kernel does Docker use on Raspberry Pi?
    By default Docker uses the standard Linux kernel included with Raspberry Pi OS. For better optimization, you can configure Docker to use Squeezelite’s docker-optimized Pi kernel instead.

  6. How do I check running Docker containers on Raspberry Pi?
    Use the docker PS command to list details on containers currently active/running on your Pi system.

  7. Where do I find Docker container logs on the Raspberry Pi?
    Docker container stdout/stderr logs are captured and stored in JSON file format in /var/lib/docker/containers/ on the Pi host system.

  8. How do I free up space from Docker on my Raspberry Pi SD card?
    Remove stopped containers with docker container prune, unused images with docker image prune, and rebuild the docker cache using docker builder prune to clean up Docker disk space.

  9. Can I run x86 Docker images on Raspberry Pi?
    No, Raspberry Pis use ARM architecture so you need to use Docker images built specifically for ARM such as official Raspberry Pi images or those you build yourself.

  10. How do I connect to a Docker container running on my Raspberry Pi?
    Use docker exec -it your-container /bin/bash to open an interactive bash shell inside a running Docker container on your Pi.

  11. How do I share files between Docker container and Raspberry Pi host?
    Use Docker volumes. For example, docker run -v /home/pi/some-folder:/data my-image mounts the /home/pi/some-folder directory on the Pi host into the /data path in the container.

  12. Can I run Docker and Kubernetes on a Raspberry Pi cluster?
    Yes, tools like k3s allow you to run Kubernetes on ARM devices like Raspberry Pis. This lets you build affordable, efficient cluster configurations.

  13. Is Docker safe to use and supported on Raspberry Pi OS?
    Yes, Docker Engine is officially packaged and supported on Raspberry Pi OS by Docker and Raspberry Pi Foundation to ensure security and seamless integration.

  14. Why do I need to add my user to the Docker group on Raspberry Pi?
    Adding your pi user to docker Linux group gives the permissions required to communicate with local Docker daemon socket for running Docker commands without sudo.

Leave a Comment