Nerdctl

Nerdctl is an open-source command-line interface (CLI) designed to be compatible with the Docker CLI, but specifically for interacting with containerd . It provides a familiar user experience for developers who are familiar with Docker, while leveraging the capabilities of containerd as the underlying container runtime.

Using containerd and nerdctl provides similar functionality to Docker but with a smaller memory footprint, making it ideal for IoT and edge solutions, especially on Arm devices that balance energy efficiency and performance.

Nerdctl also supports running containers in rootless mode, which helps enhance security by not requiring elevated privileges. Rootless mode is not covered below but you can refer to the documentation for information about how to run containerd-rootless-setuptool.sh install.

This guide explains how to install and use containerd and nerdctl on Arm Linux, and how to run commands with sudo.

What should I do before installing nerdctl?

This guide assumes you are using a Debian-based Arm Linux distribution, including Ubuntu and Raspberry Pi OS. You can use a local Arm Linux computer or an Arm instance in the cloud.

Confirm you are using an Arm machine by running:

    

        
        
uname -m

    

The output should be:

    

        
        aarch64

        
    

Ensure wget and tar are installed. Most distributions will include them, but if not, run:

    

        
        
sudo apt-get update
sudo apt-get install -y wget tar

    

How do I install containerd?

Install the containerd runtime:

    

        
        
sudo apt-get install containerd -y

    

Start and enable the containerd service:

    

        
        
sudo systemctl start containerd
sudo systemctl enable containerd

    

Confirm the service is running:

    

        
        
systemctl status containerd.service

    

When containerd is running, the output is similar to:

    

        
        ● containerd.service - containerd container runtime
     Loaded: loaded (/usr/lib/systemd/system/containerd.service; enabled; preset: enabled)
     Active: active (running) since Tue 2025-04-22 20:12:03 UTC; 2min 20s ago
       Docs: https://containerd.io
   Main PID: 8428 (containerd)
      Tasks: 9
     Memory: 13.0M (peak: 13.7M)
        CPU: 401ms
     CGroup: /system.slice/containerd.service
             └─8428 /usr/bin/containerd

        
    

How do I install nerdctl and CNI plugins?

Install nerdctl and the necessary CNI (Container Network Interface) plugins:

    

        
        
NERDCTL_VERSION=$(curl -s https://api.github.com/repos/containerd/nerdctl/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/v//')
wget https://github.com/containerd/nerdctl/releases/download/v${NERDCTL_VERSION}/nerdctl-${NERDCTL_VERSION}-linux-arm64.tar.gz
sudo tar -xzvf nerdctl-${NERDCTL_VERSION}-linux-arm64.tar.gz -C /usr/local/bin

    

Install the CNI plugins:

    

        
        
CNI_VERSION=$(curl -s https://api.github.com/repos/containernetworking/plugins/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/v//')
wget https://github.com/containernetworking/plugins/releases/download/v${CNI_VERSION}/cni-plugins-linux-arm64-v${CNI_VERSION}.tgz
sudo mkdir -p /opt/cni/bin
sudo tar -xzvf cni-plugins-linux-arm64-v${CNI_VERSION}.tgz -C /opt/cni/bin

    

Clean up the downloaded files:

    

        
        
rm nerdctl-${NERDCTL_VERSION}-linux-arm64.tar.gz cni-plugins-linux-arm64-v${CNI_VERSION}.tgz

    

How do I install BuildKit for container image building?

If you want to build container images with nerdctl, you need to install BuildKit .

If you only plan to run container images (not build them), you can skip this step.

    

        
        
BUILDKIT_VERSION=$(curl -s https://api.github.com/repos/moby/buildkit/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/v//')
wget https://github.com/moby/buildkit/releases/download/v${BUILDKIT_VERSION}/buildkit-v${BUILDKIT_VERSION}.linux-arm64.tar.gz
sudo tar -xzvf buildkit-v${BUILDKIT_VERSION}.linux-arm64.tar.gz -C /usr
rm buildkit-v${BUILDKIT_VERSION}.linux-arm64.tar.gz

    

Create a systemd service for BuildKit:

    

        
        
sudo tee /etc/systemd/system/buildkit.service > /dev/null << EOF
[Unit]
Description=BuildKit
Documentation=https://github.com/moby/buildkit

[Service]
ExecStart=/usr/bin/buildkitd --oci-worker=false --containerd-worker=true

[Install]
WantedBy=multi-user.target
EOF

    

Start and enable the BuildKit service:

    

        
        
sudo systemctl daemon-reload
sudo systemctl start buildkit
sudo systemctl enable buildkit

    

Verify BuildKit is running:

    

        
        
sudo systemctl status buildkit

    

When running, the output is similar to:

    

        
        ubuntu@m1u:~$ sudo systemctl status buildkit
● buildkit.service - BuildKit
     Loaded: loaded (/etc/systemd/system/buildkit.service; enabled; preset: enabled)
     Active: active (running) since Tue 2025-04-22 22:55:39 CDT; 18min ago
       Docs: https://github.com/moby/buildkit
   Main PID: 22280 (buildkitd)
      Tasks: 10 (limit: 4598)
     Memory: 14.6M (peak: 42.0M)
        CPU: 1.144s
     CGroup: /system.slice/buildkit.service
             └─22280 /usr/bin/buildkitd --oci-worker=false --containerd-worker=true

        
    

Check that buildctl can communicate with the daemon:

    

        
        
sudo buildctl debug workers

    

If BuildKit is properly installed, you should see output similar to:

    

        
        ID				            PLATFORMS
jz1h9gb0xq39ob6868cr3ev6r	linux/arm64

        
    

How do I verify the nerdctl installation?

You can check the nerdctl version:

    

        
        
sudo nerdctl version

    

Test your installation by running a simple container that prints the processor architecture:

    

        
        
sudo nerdctl run --name uname armswdev/uname

    

Wait a few seconds for the container to start. It will print the system architecture:

    

        
        Architecture is aarch64

        
    

Clean up the test container:

    

        
        
sudo nerdctl rm uname

    

To build a container image, save the following lines to a file named Dockerfile.

    

        
        
FROM ubuntu:latest
CMD echo -n "Architecture is " && uname -m

    

Build the container image:

    

        
        
sudo nerdctl build -t uname -f Dockerfile .

    

Run the new container image:

    

        
        
sudo nerdctl run uname

    

The output is the architecture:

    

        
        Architecture is aarch64

        
    

What are the basic nerdctl commands?

Here are some common commands to get you started:

List running containers:

    

        
        
sudo nerdctl ps

    

List all containers (including stopped):

    

        
        
sudo nerdctl ps -a

    

List images:

    

        
        
sudo nerdctl images

    

Pull an image:

    

        
        
sudo nerdctl pull <image_name>:<tag>

    

Build an image from Dockerfile in current directory:

    

        
        
sudo nerdctl build -t <image_name>:<tag> .

    

Remove an image:

    

        
        
sudo nerdctl rmi <image_name>:<tag>

    

Stop a container:

    

        
        
sudo nerdctl stop <container_name_or_id>

    

Remove a container:

    

        
        
sudo nerdctl rm <container_name_or_id>

    

View container logs:

    

        
        
sudo nerdctl logs <container_name_or_id>

    

Execute a command in a running container:

    

        
        
sudo nerdctl exec -it <container_name_or_id> <command>

    

You are now ready to use nerdctl and containerd to manage containers on Arm Linux.