This project builds and publishes Docker images for Raspberry Pi OS Lite on Docker Hub.

• Supported Architectures
• Usage
  • Docker Setup／Installation
  • Running the Images
    • Running ARM Containers on x86_64 Hosts (QEMU Setup)
      • Debian/Ubuntu
      • NixOS
      • Fedora
      • Arch Linux
• Dev Setup (How to Work on this Project)
  • Building Images Locally
    • Building 64-bit (arm64) Compatible Images
    • Building 32-bit (armhf／armel) Compatible Images
  • List Local Project Architectures
  • List Remote Image Architectures (Docker Hub Manifests)
  • Linting
    • Running Hadolint
  • Raspberry Pi OS Lite Root File System
  • Justfile

Images are published as multi-arch manifests. Use the table below to choose the right tag for your device:

This section explains how to set up Docker on your machine and work with the Raspberry Pi OS Lite images provided by this project. Follow the steps below to get started.

On macOS, you can install Docker Desktop (which includes Buildx) via Homebrew:

brew install --cask docker-desktop

After installation, launch Docker Desktop complete the setup (accepting licenses, etc.), before building any images.

These images can be used as a base for Raspberry Pi OS Lite-specific containers:

FROM webdavis/raspios-lite:arm64-20250513

# Add your own layers here...

Or run a container directly, like so:

docker run --rm -it --platform linux/arm64 webdavis/raspios-lite:arm64

Install QEMU and enable binfmt support via your system’s package manager:

sudo apt install qemu-user-static binfmt-support

Add the following to your NixOS config (/etc/nixos/configuration.nix):

environment.systemPackages = with pkgs; [
  qemu_user_static
  binfmt
];

Then run the following:

sudo nixos-rebuild switch

sudo dnf install qemu-user-static binfmt-support

sudo pacman -S qemu-user-static binfmt-support

This project requires Docker and Buildx.

Again, assuming you're on macOS, you will need to install Docker Desktop (which comes with Buildx) via Homebrew:

brew install --cask docker-desktop

Download this repo:

git clone git@github.com:webdavis/docker-raspios-lite.git

Then switch into the project directory:

cd docker-raspios-lite

Use the docker-wrapper.sh script to build and inspect project images on your dev machine.

docker-wrapper.sh is a convenience script that makes working on this project a tad easier.

To build the 64-bit variant for an arm64 architecture, run the following command:

./docker-wrapper.sh -a -o

Note: The -o option will append the --load flag to the docker command, which loads the built image into Docker so that you can run it locally.

When building a 32-bit image with the -h flag, you must specify which Platform the image should be built for, for example armv7 or armv6. The following table will help you:

• armv7 → linux/arm/v7 (most models: Pi 2, 3, 4, Zero 2)
• armv6 → linux/arm/v6 (Pi Zero v1, Pi 1, legacy)
• arm64 → linux/arm64 (32-bit on 64-bit hardware)

For example, run the following command to build and load a 32-bit image for Pi 2/3/4/Zero 2:

./docker-wrapper.sh -h armv7 -o

The following command lists the architectures this project has built locally on your machine:

./docker-wrapper.sh -l

The command below lists the image manifests from Docker Hub that are tracked by this project, which shows all available platforms (architectures/OS variants) that the image supports.

./docker-wrapper.sh -r

This project uses Hadolint to enforce Dockerfile best practices.

Hadolint can be installed using Homebrew:

brew install hadolint

To lint the Dockerfile, run:

hadolint Dockerfile

Linting rules for this project are defined in the .hadolint.yaml file.

The latest root file system for Raspberry Pi OS Lite is provided as root.tar.xz in Raspberry Pi's official downloads archive.

Just click on the latest version (or most recent date).

This project provides a justfile for ease-of-use.

Install it like so:

brew install just

just is a handy way to run project-specific commands.

For example, instead of typing in ./docker-wrapper.sh --arm64 --push, you can simply run:

just A

Instead of using docker image ls -a to list all Docker images, you can simply run:

just c

And then delete them all with:

just C