nerdctl: A Docker-Compatible CLI That Puts containerd's Extras Within Reach

What Problem Does nerdctl Solve?

containerd is a high-performance container runtime, but its native CLI, ctr, is bare-bones and not designed for everyday container workflows. Docker, on the other hand, offers a polished user experience but hides containerd's advanced capabilities. nerdctl bridges that gap by providing a Docker-compatible CLI for containerd, so you can use familiar commands like `nerdctl run`, `nerdctl build`, and `nerdctl compose up` while gaining access to containerd features that Docker does not expose. The README states that the goal is to facilitate experimenting with containerd's cutting-edge features, not to compete with Docker. This makes nerdctl a tool for developers and operators who want to stay close to containerd, perhaps for Kubernetes debugging or edge deployments, without abandoning the Docker mental model. It is also useful for those who need to run containers in rootless mode with better performance than Docker's default, or who want to pull images lazily to save bandwidth and storage.

How It Works: A CLI Over containerd with Optional Add-Ons

nerdctl is a single binary that talks to the containerd daemon via its gRPC API. It does not replace containerd; it sits on top of it, much like Docker CLI sits on top of Docker Engine, but here the runtime is containerd directly. The default networking uses a bridge CNI network with a 10.4.0.0/24 subnet, which means CNI plugins must be installed for `nerdctl run` to work. For building images, nerdctl relies on BuildKit, which is an optional dependency; the `nerdctl build` command requires the BuildKit daemon (`buildkitd`) to be running. The CLI supports namespaces, so you can target a specific containerd namespace with `--namespace=<NS>`, which is particularly handy for inspecting Kubernetes containers that live in the `k8s.io` namespace. The advanced features are implemented as optional snapshotter integrations or external daemons. For example, lazy pulling with Stargz requires a stargz snapshotter, and IPFS distribution requires an IPFS daemon. The README is explicit that your host is not connected to any P2P network unless you opt in to install and run the IPFS daemon. This modular design keeps the core CLI lightweight, but it also means that to use those features you must manage additional moving parts.

Getting It Running: Installation and Basic Commands

The simplest way to get nerdctl is to download a binary from the GitHub releases page. There are two tarball variants: a minimal one that contains only nerdctl, and a `nerdctl-full` tarball that includes containerd, CNI plugins, BuildKit, RootlessKit, and other dependencies. On Linux, you can also install it via Homebrew with `brew install nerdctl`, though that is not supported on macOS. For macOS, the recommended path is to use Lima, which provides a Linux VM with built-in nerdctl integration: `brew install lima`, then `limactl start`, then `lima nerdctl run ...`. On Windows, you can install nerdctl via Scoop, but note that Linux containers are known to work on WSL2, while Windows containers are experimental. Once installed, the basic workflow mirrors Docker. To run a container, use `nerdctl run -it --rm alpine`. To build an image, use `nerdctl build -t foo /some-dockerfile-directory`. To run a Compose stack, use `nerdctl compose -f ./examples/compose-wordpress/docker-compose.yaml up`. For rootless mode, you first run `containerd-rootless-setuptool.sh install`, then use nerdctl as a non-root user. The README gives an example of running nginx in rootless mode with `nerdctl run -d -p 8080:80 --name nginx nginx:alpine`.

The Compelling Features Docker Lacks: Lazy Pulling, Encryption, IPFS, and Cosign

nerdctl's main selling point is access to containerd features that are not present in Docker. The README lists several major ones. On-demand image pulling, also called lazy pulling, works with Stargz, Nydus, OverlayBD, or SOCI snapshotter. You enable it by passing `--snapshotter=stargz` (or the appropriate name) to `nerdctl run`. This can dramatically reduce the time to start a container because the image layers are fetched on demand rather than all at once. Image encryption and decryption is supported via ocicrypt: `nerdctl image encrypt SRC DST` and `nerdctl image decrypt SRC DST`. P2P image distribution via IPFS is available with `nerdctl run ipfs://CID`, which could be useful for air-gapped or bandwidth-constrained environments, but it requires an IPFS daemon. Finally, cosign integration allows you to verify images on pull with `nerdctl pull --verify=cosign` and sign on push with `nerdctl push --sign=cosign`, and it also works in Compose. These features are genuinely advanced and not available in stock Docker, which makes nerdctl attractive for security-conscious or performance-sensitive workloads.

Limitations and Failure Modes: Not a Drop-In Docker Replacement

nerdctl is not a perfect Docker clone. The README notes that Windows container support is experimental, and the feature list for Windows is limited. On macOS, you cannot run nerdctl directly; you need Lima or a similar VM, which adds overhead. The dependency on BuildKit for building images means that `nerdctl build` will fail if `buildkitd` is not running, and some features like `nerdctl system prune` require BuildKit v0.11.0 or later. The optional features are also double-edged: if you use lazy pulling, you must ensure the snapshotter daemon is running and configured correctly; otherwise, image pulls may fail or fall back to the default overlayfs. Similarly, IPFS mode requires an IPFS daemon, and the README warns that your host is not connected to a P2P network unless you opt in. The rootless mode, while accelerated by bypass4netns, still requires RootlessKit v0.10.0 or later, and it may not support all features that work in rootful mode. Also, because nerdctl is a non-core sub-project of containerd, the release cadence and long-term support may be less predictable than Docker's. If you need a battle-tested CLI with a huge ecosystem of tutorials and tooling, nerdctl might be the wrong tool for production without thorough testing.

Alternatives: Docker CLI and Podman

The most obvious alternative is the Docker CLI itself, which works with Docker Engine and offers the same user experience but without containerd's advanced features. Docker is more mature, has a larger ecosystem, and is better documented for end users. However, if you want those advanced features, you cannot get them with Docker; you would need to use containerd's native tools like `ctr` or `crictl`, which are less user-friendly. Another alternative is Podman, which is a daemonless container CLI that is also Docker-compatible. Podman does not rely on containerd; it uses its own runtime (usually runc or crun) and supports rootless mode natively. Podman also supports Compose via `podman-compose`, but it does not offer the same lazy pulling or IPFS features that nerdctl does. The key difference is that nerdctl is built specifically for containerd, so it can leverage containerd's snapshotter and namespace features, while Podman is a standalone tool that does not integrate with containerd. If your infrastructure is already built around containerd (for example, in Kubernetes nodes), nerdctl is a natural fit; otherwise, Podman might be simpler to adopt because it does not require a separate daemon.

Maintenance, Upgrade Cost, and License

nerdctl is an active project under the containerd organization, with recent releases including v2.3.5 and v2.4.0-beta.0 as of August 2026. It is licensed under Apache-2.0, which is permissive and allows commercial use without copyleft obligations, but you should review the license terms for any modifications you make. The upgrade cost is moderate: because nerdctl is a single binary, upgrading is as simple as replacing the binary, but you must also keep its dependencies in sync. For example, if you use BuildKit, you need to ensure the versions are compatible; the README recommends BuildKit v0.11.0 or later. The optional features require separate daemons (snapshotter, IPFS, etc.), each with its own upgrade cycle. The README does not provide a detailed changelog or migration guide, so you should check the release notes for breaking changes. Given that nerdctl is a non-core sub-project, the maintenance commitment may be lower than for containerd itself, but the project appears to be actively maintained with regular releases. If you adopt nerdctl, budget time for testing upgrades, especially if you rely on the optional features.

Editorial conclusion

Adopt nerdctl if you are already running containerd (especially in Kubernetes or edge environments) and want a Docker-like experience plus access to lazy pulling, image encryption, IPFS distribution, and rootless acceleration. Do not adopt it if you need a drop-in Docker replacement for production without verifying the readiness of its optional components; the core CLI is stable but features like Windows containers and some compose commands remain experimental. Before adopting, verify that your containerd version is compatible, that CNI plugins v1.1.0 or later are installed, and that BuildKit v0.11.0 or later is running if you need `nerdctl build`. Also check the docs for the specific snapshotter (Stargz, Nydus, OverlayBD, SOCI) you plan to use, because each requires a separate snapshotter daemon and configuration. If you need a mature, fully supported container CLI with a large ecosystem, stick with Docker or podman; nerdctl is best for those who want to experiment with containerd's cutting-edge features today.

Official sources

1. Official README
2. Project repository
3. Release notes