Skip to content

nerdctl — the Docker-compatible CLI for containerd

Use nerdctl to talk to containerd with Docker-equivalent commands — run containers, build images via BuildKit, and use compose without a Docker daemon.

nerdctl is the operator-facing CLI for containerd: the same verbs docker ships with, the same flags, the same expected behaviour, but talking to containerd’s socket directly. For hosts that have moved off the Docker daemon to containerd-only — Kubernetes nodes, lean servers, security-hardened environments — nerdctl is what restores the familiar workflow. It also includes namespaces, image encryption, lazy-pull, and other features Docker does not have.

How to verify

A working nerdctl install responds to these probes:

nerdctl --version
nerdctl info
nerdctl namespace ls
nerdctl ps -a
nerdctl images
docker --version 2>/dev/null || echo "no docker — that's fine"

nerdctl info shows which containerd it is talking to and which BuildKit it can use for image builds. The namespace setup is the same as ctr — Kubernetes objects live in k8s.io, nerdctl defaults to default.

What’s happening

nerdctl is a Go binary that translates Docker-style commands into the same containerd API calls that kubelet and ctr make. Where ctr is the surgical tool that requires you to think in OCI primitives, nerdctl provides the muscle memory of docker run -d -p 8080:80 --restart=always. Internally, networking goes through CNI (not Docker’s docker0 bridge), image builds go through BuildKit (not the legacy Docker builder), and storage goes through containerd-stargz or overlayfs depending on configuration.

The -n flag selects the namespace, but unlike ctr, nerdctl’s default namespace is default rather than k8s.io. To inspect Kubernetes pods, pass -n k8s.io explicitly. This separation prevents nerdctl operations from accidentally disturbing kubelet-managed state.

nerdctl compose is a built-in: no plugin install, no separate binary. The compose syntax is a near-superset of Docker’s, with extensions for image encryption and stargz lazy-pull.

The procedure

  1. Install nerdctl. The simplest path is the full bundle (includes BuildKit and CNI plugins):
ARCH=$(dpkg --print-architecture)
NERDCTL_VERSION=1.7.6
curl -fsSL https://github.com/containerd/nerdctl/releases/download/v${NERDCTL_VERSION}/nerdctl-full-${NERDCTL_VERSION}-linux-${ARCH}.tar.gz \
  | sudo tar Cxzvvf /usr/local -
sudo systemctl enable --now buildkit
nerdctl --version
  1. Run a container the Docker way. nerdctl picks up the host’s CNI plugins for port publishing:
nerdctl run -d --name web \
  -p 8080:80 \
  --restart=always \
  docker.io/library/nginx:alpine

nerdctl ps
curl -I http://localhost:8080
  1. Build an image with BuildKit, no Docker daemon involved:
cat > Dockerfile <<'EOF'
FROM alpine:3.19
RUN apk add --no-cache curl
CMD ["curl", "--version"]
EOF

nerdctl build -t myimage:dev .
nerdctl run --rm myimage:dev
  1. Use compose on a host without Docker. The compose syntax works identically:
# compose.yaml
services:
  redis:
    image: docker.io/library/redis:7-alpine
    restart: always
  app:
    image: ghcr.io/example/api:1.2.3
    depends_on:
      - redis
    ports:
      - "3000:3000"
    environment:
      REDIS_URL: redis://redis:6379
nerdctl compose up -d
nerdctl compose ps
nerdctl compose logs -f app
nerdctl compose down
  1. Inspect Kubernetes-managed containers from the same CLI. The namespace flag opens a window into kubelet’s state:
sudo nerdctl -n k8s.io ps
sudo nerdctl -n k8s.io logs <container-id>
sudo nerdctl -n k8s.io inspect <container-id> | jq .ProcessLabel

This is enormously useful on Kubernetes nodes — operators who know docker logs muscle memory can debug pods without learning crictl first.

  1. Use stargz lazy-pull for fast container starts. With stargz-converted images, only the bytes the container actually reads are downloaded:
nerdctl --snapshotter=stargz \
  run --rm ghcr.io/stargz-containers/postgres:13-esgz \
  psql --version

The image is huge on the registry, but the container starts in under a second because the binary’s pages are streamed on demand.

Common pitfalls

  • Forgetting that nerdctl operates in default namespace by default — running nerdctl ps on a Kubernetes node shows nothing while pods are clearly running.
  • Mixing nerdctl’s network with Docker’s. If both are installed and both have CNI/bridge configurations, you get IP conflicts. Pick one.
  • Building images with nerdctl build and expecting them to appear in the moby namespace. They go to whatever namespace nerdctl is using (default default).
  • Using --restart=always and expecting systemd-style respawn after host reboot. nerdctl restart policies are containerd-level and require the containerd-restart shim to be in place — confirm with systemctl status containerd.
  • Trusting nerdctl compose parity with docker compose 100%. Most directives work, but newer Docker compose features (secrets v2, configs v2, depends-on healthcheck conditions) may lag.

Stack Harbor uses nerdctl as the operator-facing CLI on containerd-only client hosts — see managed operations for the bundled install, the namespace policies, and the compose stacks we standardise across fleets of Kubernetes-runtime-only nodes.