# nerdctl — Docker-Compatible CLI for containerd

> Run containers with familiar Docker commands directly on containerd, gaining rootless mode, lazy-pulling, and encrypted images without the Docker daemon.

## Install

Save as a script file and run:

# nerdctl — Docker-Compatible CLI for containerd

## Quick Use
```bash
# Install full bundle (containerd + nerdctl + CNI + BuildKit)
curl -fsSL https://github.com/containerd/nerdctl/releases/download/v2.1.0/nerdctl-full-2.1.0-linux-amd64.tar.gz | sudo tar xz -C /usr/local

# Run a container
nerdctl run -d --name web -p 8080:80 nginx
```

## 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

---
Source: https://tokrepo.com/en/workflows/08e685fd-3de4-11f1-9bc6-00163e2b0d79
Author: Script Depot