# Nerdctl

## About this Install Guide

|  |  |
| --- | --- |
| Reading time: | 10 min |
| Last updated: | 22 Jun 2026 |

|  |  |
| --- | --- |
| Author: | Jason Andrews , Arm<br>[GitHub](https://github.com/jasonrandrews)<br>[LinkedIn](https://linkedin.com/in/jason-andrews-7b05a8) |
| Official docs: | [View](https://github.com/containerd/nerdctl/blob/main/docs/command-reference.md) |

This guide shows you how to install and use the tool with the most common configuration. For advanced options and complete reference information, see the official documentation. Some install guides also include optional next steps to help you explore related workflows or integrations.

[Nerdctl](https://github.com/containerd/nerdctl) is an open-source command-line interface (CLI) designed to be compatible with the Docker CLI, but specifically for interacting with [containerd](https://containerd.io/). 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](https://rootlesscontaine.rs/getting-started/containerd/) 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:

```
__output__ 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:

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

> **Note**: The commands above attempt to fetch the latest versions automatically. If required, you can replace `${NERDCTL_VERSION}` and `${CNI_VERSION}` with specific versions.

## How do I install BuildKit for container image building?

If you want to build container images with `nerdctl`, you need to install [BuildKit](https://github.com/moby/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:

```
__output__ ubuntu@m1u:~$ sudo systemctl status buildkit
__output__ ● buildkit.service - BuildKit
__output__      Loaded: loaded (/etc/systemd/system/buildkit.service; enabled; preset: enabled)
__output__      Active: active (running) since Tue 2025-04-22 22:55:39 CDT; 18min ago
__output__        Docs: https://github.com/moby/buildkit
__output__    Main PID: 22280 (buildkitd)
__output__       Tasks: 10 (limit: 4598)
__output__      Memory: 14.6M (peak: 42.0M)
__output__         CPU: 1.144s
__output__      CGroup: /system.slice/buildkit.service
__output__              └─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:

```
__output__ ID                             PLATFORMS
__output__ 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:

```
__output__ 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:

```
__output__ 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.