Technotes for future me

How to use nerdctl if you are familiar with Docker CLI

nerdctl is a relatively new command-line client for containerd. Unlike ctr, nerdctl aims to be user-friendly and Docker-compatible. To some extent, nerdctl + containerd can seamlessly replace docker + dockerd. However, [this does not seem to be the main goal of the project(].

From the basic usage standpoint, comparing to ctr, nerdctl supports:

  • Image building with nerdctl build (BuildKit required) Container networking management

  • Docker Compose with nerdctl compose up

And the coolest part about it isthat nerdctl tries to provide the identical to docker command-line UX. So, if you are familiar with docker CLI,you are allready familiar with nerdctl.

Basic usage

To run a container with the default bridge CNI network (

# nerdctl run -it --rm alpine

To build an image using BuildKit:

# nerdctl build -t foo /some-dockerfile-directory
# nerdctl run -it --rm foo

To build and send output to a local directory using BuildKit:

# nerdctl build -o type=local,dest=. /some-dockerfile-directory

To run containers from docker-compose.yaml:

# nerdctl compose -f ./examples/compose-wordpress/docker-compose.yaml up

See also [./examples/compose-wordpress](

Debugging Kubernetes

To list local Kubernetes containers:

# nerdctl --namespace ps -a

To build an image for local Kubernetes without using registry:

# nerdctl --namespace build -t foo /some-dockerfile-directory
# kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
  name: foo
    - name: foo
      image: foo
      imagePullPolicy: Never

To load an image archive (docker save format or OCI format) into local Kubernetes:

# nerdctl --namespace load < /path/to/image.tar

To read logs (experimental):

# nerdctl ps -a
CONTAINER ID    IMAGE                                                      COMMAND                   CREATED          STATUS    PORTS    NAMES
e8793b8cca8b                     "/coredns -conf /etc…"    2 minutes ago    Up                 k8s://kube-system/coredns-787d4945fb-mfx6b/coredns

# nerdctl logs -f e8793b8cca8b
[INFO] plugin/reload: Running configuration SHA512 = 591cf328cccc12bc490481273e738df59329c62c0b729d94e8b61db9961c2fa5f046dd37f1cf888b953814040d180f52594972691cd6ff41be96639138a43908
linux/amd64, go1.18.2, 45b0a11



Last updated on 20 Jun 2023
Published on 20 Jun 2023
Edit on GitHub