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
- 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
- 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
- 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
- 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
- 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.
- 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
defaultnamespace by default — runningnerdctl pson 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 buildand expecting them to appear in themobynamespace. They go to whatever namespace nerdctl is using (defaultdefault). - Using
--restart=alwaysand expecting systemd-style respawn after host reboot. nerdctl restart policies are containerd-level and require the containerd-restart shim to be in place — confirm withsystemctl status containerd. - Trusting
nerdctl composeparity withdocker compose100%. 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.