nerdctl — Docker-Compatible CLI for containerd

Introduction

nerdctl is a Docker-compatible CLI that talks directly to containerd instead of going through the Docker daemon. It gives you the same UX you already know while unlocking containerd-native features like rootless containers, image encryption, and lazy-pulling with Stargz/Nydus.

What nerdctl Does

• Implements the Docker CLI surface (run, build, compose, push, pull) on top of containerd
• Supports rootless container execution out of the box for non-root users
• Enables lazy-pulling of container images via eStargz and Nydus formats
• Builds images through BuildKit with full Dockerfile compatibility
• Runs Docker Compose files using the nerdctl compose subcommand

Architecture Overview

nerdctl is a standalone Go binary that communicates with the containerd daemon via its gRPC API. For networking it relies on CNI plugins rather than Docker's libnetwork, which means any CNI-compliant plugin works. Image builds are delegated to BuildKit running as a containerd-managed process. For rootless operation nerdctl uses rootlesskit and slirp4netns to create unprivileged network namespaces.

Self-Hosting & Configuration

• Download the minimal package (nerdctl binary only) or the full bundle that includes containerd, BuildKit, and CNI plugins
• Set up rootless mode with containerd-rootless-setuptool.sh install for unprivileged container execution
• Configure containerd hosts via /etc/containerd/certs.d/ for private registry mirrors and TLS certificates
• Enable eStargz lazy-pulling by setting snapshotter = "stargz" in the containerd config
• Use nerdctl compose to run multi-container stacks defined in standard Docker Compose YAML files

Key Features

• Near-complete Docker CLI compatibility means existing scripts and muscle memory transfer directly
• Rootless containers run without any daemon running as root, reducing the attack surface
• Image encryption with OCICRYPT lets you push encrypted images that require decryption keys to pull
• P2P image distribution via IPFS integration for air-gapped or bandwidth-constrained environments
• Namespace isolation lets multiple users share one containerd instance without seeing each other's containers

Comparison with Similar Tools

• Docker CLI — the industry standard; nerdctl drops the daemon dependency and adds rootless, encryption, and lazy-pull features
• Podman — also daemonless and rootless; nerdctl targets containerd specifically and shares the Kubernetes runtime layer
• crictl — low-level CRI debugging tool; nerdctl provides a full user-facing CLI with build, compose, and push support
• Lima — runs Linux VMs on macOS to host containerd; nerdctl is the CLI that Lima exposes inside those VMs
• Finch — AWS minimal container toolkit; Finch bundles nerdctl with Lima under the hood

FAQ

Q: Can nerdctl fully replace Docker? A: For most developer workflows yes. A few Docker-specific features (Swarm mode, some plugin APIs) are not supported since they depend on the Docker daemon.

Q: Does nerdctl work with Kubernetes? A: nerdctl targets the same containerd runtime that Kubernetes uses, so images built with nerdctl are immediately available to kubelet without extra push/pull steps.

Q: How does rootless mode work? A: nerdctl runs containerd in a user namespace via rootlesskit. No root privileges are needed for pulling, building, or running containers.

Q: Is nerdctl compatible with Docker Compose files? A: Yes. nerdctl compose supports Compose Spec v2/v3 files. Some advanced Compose features may differ in behavior since the networking stack uses CNI.

Sources

• https://github.com/containerd/nerdctl
• https://github.com/containerd/nerdctl/blob/main/docs/README.md