# Nerdctl

## About this Install Guide
| Reading time: | 10 min |
|---------------|--------|
| Last updated: | 22 Jun 2026 |
| Author: | Jason Andrews, Arm [GitHub](https://github.com/jasonrandrews) [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:

```bash
uname -m
```

The output should be:

```
__output__
aarch64
```

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

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

## How do I install containerd?
Install the `containerd` runtime:

```bash
sudo apt-get install containerd -y
```

Start and enable the `containerd` service:

```bash
sudo systemctl start containerd
sudo systemctl enable containerd
```

Confirm the service is running:

```bash
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
          └─8428 /usr/bin/containerd
```

## How do I install nerdctl and CNI plugins?
Install `nerdctl` and the necessary CNI (Container Network Interface) plugins:

```bash
NERDCTL_VERSION=$(curl -s https://api.github.com/repos/containerd/nerdctl/releases/latest | grep tag_name | cut -d'"' -f4 | 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:

```bash
CNI_VERSION=$(curl -s https://api.github.com/repos/containernetworking/plugins/releases/latest | grep tag_name | cut -d'"' -f4 | 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:

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

```bash
BUILDKIT_VERSION=$(curl -s https://api.github.com/repos/moby/buildkit/releases/latest | grep tag_name | cut -d'"' -f4 | 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 /
rm buildkit-v${BUILDKIT_VERSION}.linux-arm64.tar.gz
```

Create a systemd service for BuildKit:

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

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

Verify BuildKit is running:

```bash
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
             └─22280 /usr/bin/buildkitd --oci-worker=false --containerd-worker=true
```

Check that buildctl can communicate with the daemon:

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

```bash
sudo nerdctl version
```

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

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

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

```bash
sudo nerdctl build -t uname -f Dockerfile .
```

Run the new container image:

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

```bash
sudo nerdctl ps
```

List all containers (including stopped):

```bash
sudo nerdctl ps -a
```

List images:

```bash
sudo nerdctl images
```

Pull an image:

```bash
sudo nerdctl pull <image_name>:<tag>
```

Build an image from Dockerfile in current directory:

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

Remove an image:

```bash
sudo nerdctl rmi <image_name>:<tag>
```

Stop a container:

```bash
sudo nerdctl stop <container_name_or_id>
```

Remove a container:

```bash
sudo nerdctl rm <container_name_or_id>
```

View container logs:

```bash
sudo nerdctl logs <container_name_or_id>
```

Execute a command in a running container:

```bash
sudo nerdctl exec -it <container_name_or_id> <command>
```

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