Unlock Docker Compatibility with nerdctl: A Guide to Containerd’s Powerful CLI

1. What is nerdctl

nerdctl is a command‑line interface that offers the same user experience as Docker while being built directly on the industry‑standard container runtime containerd. It serves as a drop‑in replacement for Docker CLI commands and exposes experimental features not yet available in Docker.

Using nerdctl you can:

Run familiar Docker commands such as run, build, push, etc.

Handle Docker Compose files.

Access advanced capabilities like lazy pulling, image encryption, and peer‑to‑peer image distribution.

Operate in rootless mode without performance overhead.

2. Main Features

2.1 Docker Compatibility

nerdctl fully supports Docker CLI syntax, allowing seamless switching between the two tools. Example commands:

# nerdctl run -it --rm alpine
# nerdctl build -t foo /some-dockerfile-directory
# nerdctl compose -f ./docker-compose.yaml up

This compatibility also extends to Docker Compose, enabling multi‑container applications to run without modification.

2.2 nerdctl vs. crictl

crictl is designed specifically for Kubernetes CRI compatibility and does not support many non‑CRI features that simplify development. While Docker provides a full container platform, nerdctl focuses on being a lightweight CLI that leverages containerd directly, offering experimental functions and a more modular architecture.

3. Installation

Option 1: Binary installation (recommended)

# Download the latest release
wget https://github.com/containerd/nerdctl/releases/download/v1.7.0/nerdctl-full-1.7.0-linux-amd64.tar.gz
# Extract and install
sudo tar -C /usr/local -xzf nerdctl-full-1.7.0-linux-amd64.tar.gz

Option 2: Package manager

For macOS, the recommended approach is to use Lima, which provides a Linux VM with built‑in nerdctl support.

brew install lima
limactl start lima
nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine

4. Basic Commands

After installing nerdctl, you can use familiar Docker‑style commands.

Running containers

# Run an interactive container
nerdctl run -it --rm alpine

# Run a container in detached mode
nerdctl run -d --name nginx -p 8080:80 nginx:alpine

# List running containers
nerdctl ps

# Stop and remove a container
nerdctl stop nginx
nerdctl rm nginx

Building images

nerdctl integrates with BuildKit to provide powerful image‑building capabilities:

# Build a simple image
nerdctl build -t my-app ./path/to/dockerfile

# Run the newly built image
nerdctl run -it --rm my-app

# Build and export to a local directory
nerdctl build -o type=local,dest=./output ./path/to/dockerfile

Docker Compose integration

One of nerdctl’s advantages is native support for Docker Compose:

# Start services defined in a compose file
nerdctl compose -f docker-compose.yaml up

# Run in detached mode
nerdctl compose -f docker-compose.yaml up -d

# Stop services
nerdctl compose -f docker-compose.yaml down

# View compose logs
nerdctl compose -f docker-compose.yaml logs

5. Conclusion

nerdctl provides a familiar Docker‑compatible interface while unlocking the powerful features of containerd. Whether you are a developer eager to try the latest container capabilities or a system administrator seeking a lightweight management tool, nerdctl offers an attractive solution.