nerdctl

What it is

A Docker-compatible CLI for managing containers, images, and volumes, often used with containerd as the underlying runtime, especially in Kubernetes environments.

Installation

Linux

# Example for Debian/Ubuntu based systems using apt
sudo apt-get update
sudo apt-get install -y containerd.io
sudo systemctl enable --now containerd

# Download nerdctl binary
curl -LO https://github.com/containerd/nerdctl/releases/download/v1.7.0/nerdctl-1.7.0-linux-amd64.tar.gz
sudo tar xzf nerdctl-1.7.0-linux-amd64.tar.gz -C /usr/local/bin
rm nerdctl-1.7.0-linux-amd64.tar.gz

# Verify installation
nerdctl --version

macOS

# Using Homebrew
brew install nerdctl

Windows

(Refer to the official nerdctl documentation for the most up-to-date instructions as Windows installation can be more involved and may require WSL2.)

Core Concepts

• Containerd: The underlying container runtime that nerdctl interacts with. nerdctl provides a Docker-like API on top of containerd.
• Image: A read-only template used to create containers. Similar to Docker images.
• Container: A runnable instance of an image. Similar to Docker containers.
• Volume: A mechanism for persisting data generated by and used by Docker containers.
• Network: A virtual network for containers to communicate.

Commands / Usage

Managing Containers

Listing Containers

# List all containers (including stopped ones)
nerdctl ps -a

# List running containers
nerdctl ps

# List containers with detailed information
{% raw %}
nerdctl ps -a --format "table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.Status}}\t{{.Names}}"
{% endraw %}

Running Containers

# Run a container in the background
nerdctl run -d --name my-nginx nginx:latest

# Run a container interactively with a TTY
nerdctl run -it --rm ubuntu:latest bash

# Run a container with port mapping
nerdctl run -d -p 8080:80 --name my-webserver nginx:latest

# Run a container with a volume mount
nerdctl run -d -v /path/on/host:/path/in/container --name my-data-app alpine:latest

# Run a container with environment variables
nerdctl run -d -e MY_VAR=my_value --name my-env-app alpine:latest

# Run a container with a specific network
nerdctl network create my-net
nerdctl run -d --network my-net --name my-net-app alpine:latest

Stopping and Starting Containers

# Stop a running container
nerdctl stop my-nginx

# Start a stopped container
nerdctl start my-nginx

# Restart a container
nerdctl restart my-nginx

# Kill a container (sends SIGKILL)
nerdctl kill my-nginx

Removing Containers

# Remove a stopped container
nerdctl rm my-nginx

# Force remove a running container
nerdctl rm -f my-nginx

# Remove all stopped containers
nerdctl container prune -f

Inspecting Containers

# Get detailed information about a container
nerdctl inspect my-nginx

# View container logs
nerdctl logs my-nginx

# Stream container logs
nerdctl logs -f my-nginx

# Execute a command inside a running container
nerdctl exec -it my-nginx bash

Managing Images

Listing Images

# List all images
nerdctl images

# List images with specific filters (e.g., by repository name)
nerdctl images --filter "reference=nginx:*"

# List images with detailed information
{% raw %}
nerdctl images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"
{% endraw %}

Pulling Images

# Pull an image from a registry
nerdctl pull nginx:latest

# Pull a specific tag of an image
nerdctl pull ubuntu:22.04

Building Images

# Build an image from a Dockerfile in the current directory
nerdctl build -t my-custom-app:v1 .

# Build an image with a specific Dockerfile and context
nerdctl build -f Dockerfile.prod -t my-prod-app:latest .

# Build an image with build arguments
nerdctl build --build-arg VERSION=1.0 -t my-app:latest .

Tagging Images

# Tag an existing image with a new name and tag
nerdctl tag nginx:latest my-registry.local/my-nginx:v1.0

Pushing Images

# Push an image to a registry
nerdctl push my-registry.local/my-nginx:v1.0

Removing Images

# Remove an image
nerdctl rmi nginx:latest

# Force remove an image (even if used by a container)
nerdctl rmi -f nginx:latest

# Remove all unused images
nerdctl image prune -f

Inspecting Images

# Get detailed information about an image
nerdctl inspect nginx:latest

Managing Volumes

Listing Volumes

# List all volumes
nerdctl volume ls

# List volumes with specific filters
nerdctl volume ls --filter "name=my-data"

Creating Volumes

# Create a named volume
nerdctl volume create my-data-volume

Removing Volumes

# Remove a volume
nerdctl volume rm my-data-volume

# Remove all unused volumes
nerdctl volume prune -f

Inspecting Volumes

# Get detailed information about a volume
nerdctl volume inspect my-data-volume

Managing Networks

Listing Networks

# List all networks
nerdctl network ls

# List networks with specific filters
nerdctl network ls --filter "name=my-net"

Creating Networks

# Create a bridge network
nerdctl network create my-bridge-net

# Create a host network
nerdctl network create --driver host my-host-net

Removing Networks

# Remove a network
nerdctl network rm my-bridge-net

Inspecting Networks

# Get detailed information about a network
nerdctl network inspect my-bridge-net

Connecting/Disconnecting Containers from Networks

# Connect a running container to a network
nerdctl network connect my-bridge-net my-nginx

# Disconnect a container from a network
nerdctl network disconnect my-bridge-net my-nginx

System Management

Information

# Display system-wide information
nerdctl info

# Display version information
nerdctl version

Cleanup

# Remove all stopped containers, unused networks, dangling images, and build cache
nerdctl system prune -f

Common Patterns

Running a web server and accessing it locally:

nerdctl run -d -p 8080:80 --name my-webserver nginx:latest
# Access http://localhost:8080 in your browser

Persisting data for a database:

nerdctl volume create my-db-data
nerdctl run -d -v my-db-data:/var/lib/mysql --name my-mysql mysql:latest

Building an application and running it:

# Assuming you have a Dockerfile in the current directory
nerdctl build -t my-app:latest .
nerdctl run -d --name my-running-app my-app:latest

Copying files to/from a container:

# Copy a file from host to container
nerdctl cp ./local-file.txt my-container:/app/remote-file.txt

# Copy a file from container to host
nerdctl cp my-container:/app/log.txt ./host-log.txt

Running a container with a specific entrypoint:

nerdctl run -d --entrypoint "/bin/sh" --name my-sh-container alpine:latest -c "while true; do echo hello; sleep 1; done"

Running a container and getting a shell immediately:

nerdctl run -it --rm alpine:latest sh

Cleaning up unused resources:

# Remove stopped containers and dangling images
nerdctl container prune -f
nerdctl image prune -f

Gotchas

• Rootless Mode: nerdctl can be run in rootless mode, which has implications for networking and resource allocation. Ensure you understand the limitations if using rootless.
• Containerd Configuration: nerdctl relies on containerd’s configuration. Sometimes, issues might stem from containerd.toml rather than nerdctl itself.
• Docker Compatibility: While nerdctl aims for Docker compatibility, there might be minor differences or features not yet fully implemented. Always check the official nerdctl documentation for specific versions.
• docker-compose: nerdctl does not directly support docker-compose. For orchestration, you would typically use Kubernetes or another tool.
• Image Naming: Be mindful of image naming conventions, especially when pushing to private registries (e.g., my-registry.local/my-image:tag).