Contents

How to install containerd on Raspberry Pi

You should be running Raspberry Pi OS based on Debian Bookworm (Debian 12) or Bullseye. Modern Raspberry Pi models (Pi 3, 4, 5, Zero 2 W) can run either 64-bit (arm64) or 32-bit (armhf) OS images, while older models (Pi 1, 2, Zero) run 32-bit (armhf/armv6l).

Before starting, update your package lists and installed packages:

sudo apt update
sudo apt full-upgrade -y

We need Go to compile runc and containerd.

Download and extract the Go archive matching your Pi architecture (check Go downloads for other versions):

wget https://go.dev/dl/go1.23.6.linux-arm64.tar.gz
sudo tar -C /usr/local -xzf go1.23.6.linux-arm64.tar.gz
rm go1.23.6.linux-arm64.tar.gz
wget https://go.dev/dl/go1.23.6.linux-armv6l.tar.gz
sudo tar -C /usr/local -xzf go1.23.6.linux-armv6l.tar.gz
rm go1.23.6.linux-armv6l.tar.gz

Add the Go binary directory to your PATH (in ~/.profile or ~/.bashrc):

echo 'export PATH="$PATH:/usr/local/go/bin"' | tee -a $HOME/.profile
source $HOME/.profile

Verify the installation:

go version
# Example: go version go1.23.6 linux/arm64

runc is the OCI runtime used by containerd to spawn and manage container processes.

Install build dependencies and libseccomp development headers:

sudo apt install -y git make gcc pkg-config libseccomp-dev

Clone and compile runc:

git clone https://github.com/opencontainers/runc.git
cd runc
make -j$(nproc)
sudo make install
cd ..

Verify the installation:

runc --version

Install the required storage libraries and tools:

sudo apt install -y btrfs-progs libbtrfs-dev protobuf-compiler

Clone the containerd repository and check out a release tag (such as v2.0.2 for containerd v2, or v1.7.25 for containerd v1 LTS):

git clone https://github.com/containerd/containerd.git
cd containerd
git checkout v2.0.2
make -j$(nproc)
sudo make install

Verify the installation:

containerd --version
# Example: containerd github.com/containerd/containerd v2.0.2 ...

Generate a default containerd configuration file at /etc/containerd/config.toml:

sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml

Install and start the systemd unit file from the containerd repository:

sudo cp containerd.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now containerd.service

Check the status to ensure it is active and running:

sudo systemctl status containerd.service

Test the containerd client CLI (ctr):

sudo ctr version

To test running containers with local OCI images without a registry, see the companion repository rolandjitsu/containerd-oci-import. It demonstrates how to build and export OCI tar archives using Docker Buildx and interact with containerd programmatically via its Go client.