Mastering nerdctl: Docker‑compatible CLI for containerd – Features, Install & Commands

What is nerdctl

nerdctl is a command‑line interface that implements the Docker command set while directly using the containerd runtime. It acts as a drop‑in replacement for Docker, exposing experimental containerd features such as lazy image pulling, image encryption, and peer‑to‑peer distribution. It also runs in rootless mode without performance penalties.

Key features

Supports familiar Docker commands (run, build, push, etc.).

Native handling of Docker Compose files.

Access to advanced containerd capabilities like lazy pulling, image encryption, and P2P image distribution.

Rootless operation with no measurable overhead.

Docker compatibility

nerdctl mirrors Docker CLI syntax, allowing seamless substitution of Docker commands. The compatibility extends to Docker Compose, enabling multi‑container applications without modification.

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

# Build an image
nerdctl build -t foo ./path/to/dockerfile

# Use a compose file
nerdctl compose -f docker-compose.yaml up

Installation

Binary (recommended)

Download the tarball for the desired version and extract it to a directory in the system PATH, e.g., /usr/local.

wget https://github.com/containerd/nerdctl/releases/download/v1.7.0/nerdctl-full-1.7.0-linux-amd64.tar.gz
sudo tar -C /usr/local -xzf nerdctl-full-1.7.0-linux-amd64.tar.gz

Package manager (macOS)

Install Lima, which provides a Linux VM with built‑in nerdctl support, then start the VM.

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

Basic commands

Running containers

# Interactive container
nerdctl run -it --rm alpine

# Detached container with port mapping
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

# Simple build
nerdctl build -t my-app ./path/to/dockerfile

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

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

Docker Compose integration

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

# 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

Reference

Source repository: https://github.com/containerd/nerdctl