Using nerdctl with containerd: Installation, Commands, Image Management, and Buildkit Integration

Previously we introduced the ctr tool for managing containerd images, but many users are accustomed to the Docker CLI. To make the transition to containerd smoother, the community provides nerdctl (https://github.com/containerd/nerdctl), a Docker‑compatible client that also supports Docker Compose syntax.

Installation

Download the appropriate tarball from the GitHub Release page and extract it to a directory in your PATH :

# If containerd is not installed, download the full package
wget https://github.com/containerd/nerdctl/releases/download/v0.11.0/nerdctl-0.11.0-linux-amd64.tar.gz
# Alternative accelerated URL
# wget https://download.fastgit.org/containerd/nerdctl/releases/download/v0.11.0/nerdctl-0.11.0-linux-amd64.tar.gz
mkdir -p /usr/local/containerd/bin/ && tar -zxvf nerdctl-0.11.0-linux-amd64.tar.gz nerdctl && mv nerdctl /usr/local/containerd/bin/
ln -s /usr/local/containerd/bin/nerdctl /usr/local/bin/nerdctl
nerdctl version
Client:
  Version:       v0.11.0
  Git commit:    c802f934791f83dacf20a041cd1c865f8fac954e
Server:
  containerd:
    Version:     v1.5.5
    Revision:    72cec4be58a9eb6b2910f5d10f1c01ca47d231c0

After installation, you can start using the nerdctl command line tool.

Commands

Run & Exec

nerdctl run works like docker run :

nerdctl run -d -p 80:80 --name=nginx --restart=always nginx:alpine

Supported options are similar to Docker's docker run . Use nerdctl run --help for the full list.

NAME:
  nerdctl run - Run a command in a new container
USAGE:
  nerdctl run [command options] [arguments...]
OPTIONS:
  --help                     show help (default: false)
  -t, --tty                  allocate a pseudo‑TTY (default: false)
  -i, --interactive          keep STDIN open (default: false)
  -d, --detach               run container in background (default: false)
  --restart value            restart policy ("no"|"always")
  --rm                       automatically remove container on exit
  --pull value               pull image before running ("always"|"missing"|"never")
  -p, --publish value        publish container ports to the host
  --cpus value               number of CPUs (default: 0)
  --memory value             memory limit
  ... (additional Docker‑compatible options)

nerdctl exec executes a command inside a running container:

nerdctl exec -it nginx /bin/sh

Container Management

nerdctl ps lists containers (add -a to show all):

nerdctl ps

nerdctl inspect shows detailed container information, similar to docker inspect :

nerdctl inspect nginx

nerdctl logs retrieves container logs and supports options like -f , -t , -n , --since , --until :

nerdctl logs -f nginx

nerdctl stop stops a container, and nerdctl rm removes it (use -f or --force to force removal).

Image Management

nerdctl images lists images. Note that some Docker options ( --all , --digests , etc.) are not yet implemented.

nerdctl images

nerdctl pull pulls an image, nerdctl push pushes an image (requires prior nerdctl login ), nerdctl tag creates an alias, nerdctl save exports an image to a tar archive, and nerdctl load imports an archive.

Image Build

To build images, nerdctl relies on BuildKit. Install BuildKit and start its daemon:

wget https://github.com/moby/buildkit/releases/download/v0.9.0/buildkit-v0.9.0.linux-amd64.tar.gz
# Optional accelerated URL
# wget https://download.fastgit.org/moby/buildkit/releases/download/v0.9.0/buildkit-v0.9.0.linux-amd64.tar.gz
tar -zxvf buildkit-v0.9.0.linux-amd64.tar.gz -C /usr/local/containerd/
ln -s /usr/local/containerd/bin/buildkitd /usr/local/bin/buildkitd
ln -s /usr/local/containerd/bin/buildctl /usr/local/bin/buildctl
# Create systemd unit for buildkitd
cat /etc/systemd/system/buildkit.service
[Unit]
Description=BuildKit
Documentation=https://github.com/moby/buildkit
[Service]
ExecStart=/usr/local/bin/buildkitd --oci-worker=false --containerd-worker=true
[Install]
WantedBy=multi-user.target
systemctl daemon-reload
systemctl enable buildkit --now
systemctl status buildkit

After BuildKit is running, you can build an image from a Dockerfile:

FROM nginx
RUN echo 'This is a containerd‑based nginx image built with nerdctl' > /usr/share/nginx/html/index.html

nerdctl build -t nginx:nerdctl -f Dockerfile .
# Expected error if buildkitd is not running:
FATA[0000] `buildctl` needs to be installed and `buildkitd` needs to be running...

Once built, the image appears in nerdctl images (a warning about an unparsable image name may be shown but does not affect usage).

nerdctl images

Run a container from the newly built image to verify:

nerdctl run -d -p 80:80 --name=nginx --restart=always nginx:nerdctl
nerdctl ps
curl localhost

The output confirms the custom message from the Dockerfile, demonstrating that nerdctl + buildkitd can fully replace Docker for image building and container management.

Additionally, nerdctl compose and related commands ( up , down , logs , build ) provide Docker‑Compose compatibility in a containerd environment.