nerdctl Guide

Docker-Compatible Docker Compose Support Rootless Mode

nerdctl is a Docker-compatible CLI for containerd. It provides a familiar Docker-like experience while leveraging the lightweight containerd runtime. Perfect for users transitioning from Docker to containerd.

Docker Compatible Compose Support Rootless Fast & Lightweight

What is nerdctl?

nerdctl is a command-line tool that provides a Docker-compatible interface for containerd. It was created to give users a familiar experience when working with containerd, making the transition from Docker smooth and intuitive. With nerdctl, you can use the same commands you know from Docker—`pull`, `run`, `ps`, `exec`, `logs`, `build`, and even `compose`—all powered by containerd underneath.

While `ctr` (the native containerd CLI) is designed for low-level debugging, nerdctl is built for day-to-day container operations. It supports most Docker CLI commands, including advanced features like volume mounts, port publishing, and container naming. nerdctl also includes built-in support for Docker Compose, allowing you to run multi-container applications without installing additional tools.

nerdctl is the recommended CLI for containerd users who want a Docker-like experience. It's actively maintained by the containerd community and is used in production environments worldwide.

Installing nerdctl

                # Install nerdctl on Linux (AMD64)
curl -L https://github.com/containerd/nerdctl/releases/download/v1.7.0/nerdctl-1.7.0-linux-amd64.tar.gz -o nerdctl.tar.gz
sudo tar Cxzvf /usr/local/bin nerdctl.tar.gz

# Install on macOS via Homebrew
brew install nerdctl

# Install on Windows via Chocolatey
choco install nerdctl

# Verify installation
nerdctl --version
nerdctl version

# Note: containerd must be installed and running
# Check containerd status
sudo systemctl status containerd
            

nerdctl works with any containerd installation, including Docker Desktop's containerd (which runs in the `moby` namespace).

Basic Commands: Docker-Like Experience

nerdctl commands are designed to be nearly identical to Docker. If you know Docker, you already know nerdctl. Here are the most common commands you'll use daily:

nerdctl pull nginx:alpine

Pull an image from registry

nerdctl run -d --name web -p 80:80 nginx:alpine

Run container in background with port mapping

nerdctl ps

List running containers

nerdctl ps -a

List all containers (including stopped)

nerdctl stop web

Stop a running container

nerdctl start web

Start a stopped container

nerdctl rm web

Remove a stopped container

nerdctl logs web

View container logs

nerdctl exec -it web sh

Execute command in running container

nerdctl images

List images

nerdctl rmi nginx:alpine

Remove an image

nerdctl tag nginx:alpine myregistry/nginx:alpine

Tag image for registry

nerdctl push myregistry/nginx:alpine

Push image to registry

                # Full workflow example
nerdctl pull nginx:alpine
nerdctl run -d --name web -p 8080:80 nginx:alpine
nerdctl ps
nerdctl logs -f web
nerdctl exec -it web sh
nerdctl stop web
nerdctl rm web
            

Advanced Commands

                # Volume mounting
nerdctl run -v /host/data:/container/data nginx

# Environment variables
nerdctl run -e ENV=production nginx

# Interactive session
nerdctl run -it --rm alpine sh

# Resource limits
nerdctl run --memory=512m --cpus=0.5 nginx

# Restart policy
nerdctl run --restart=unless-stopped nginx

# Health check
nerdctl run --health-cmd "curl -f http://localhost/ || exit 1" nginx

# Network management
nerdctl network create mynet
nerdctl run --network mynet nginx

# Build image from Dockerfile
nerdctl build -t myapp .

# Build with BuildKit (faster)
nerdctl build -t myapp --buildkit .
            

Docker Compose Support

One of nerdctl's most powerful features is its built-in Docker Compose support. You can use the same docker-compose.yml files you already have, and nerdctl will run them using containerd.

                # docker-compose.yml
version: '3.8'
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
  app:
    build: .
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: secret

# Run compose
nerdctl compose up -d

# View services
nerdctl compose ps

# View logs
nerdctl compose logs -f

# Stop and remove
nerdctl compose down

# Stop and remove volumes
nerdctl compose down -v
            

nerdctl compose is compatible with most Docker Compose features, making it a great alternative for local development environments.

nerdctl vs Docker: Feature Comparison

Runtime

nerdctl: containerd

Docker: containerd (under the hood)

Image Building

nerdctl: Yes (via BuildKit)

Docker: Yes

Compose Support

nerdctl: Built-in

Docker: Yes

Rootless Mode

nerdctl: Supported

Docker: Limited

Resource Footprint

nerdctl: Lightweight

Docker: Heavier

Kubernetes Integration

nerdctl: Native (via containerd CRI)

Docker: Deprecated (requires cri-dockerd)

Rootless Mode: Enhanced Security

nerdctl supports rootless mode, allowing you to run containers without root privileges on the host. This significantly improves security by reducing the attack surface and impact of container escapes.

                # Check if rootless mode is active
nerdctl info | grep -i rootless

# Run rootless nerdctl (requires rootless containerd)
# nerdctl automatically detects rootless containerd

# Enable rootless mode in containerd config
# /etc/containerd/config.toml
[plugins."io.containerd.grpc.v1.cri".containerd]
  rootless = true

# Run container in rootless mode
nerdctl run --rm alpine echo "Running rootless"
            

Rootless mode has some limitations (no host network, limited cgroup support). Test your workloads before using in production.

Building Images with nerdctl

nerdctl supports building images using BuildKit, providing fast, parallel, and cache-efficient builds. The syntax is identical to Docker build.

                # Build from Dockerfile
nerdctl build -t myapp:latest .

# Build with BuildKit (default)
nerdctl build --buildkit -t myapp:latest .

# Build with cache from registry
nerdctl build --cache-from myregistry/myapp:latest -t myapp:latest .

# Build with custom Dockerfile name
nerdctl build -f Dockerfile.prod -t myapp:prod .

# Build for specific platform
nerdctl build --platform linux/amd64,linux/arm64 -t myapp:multi .
            

Working with Namespaces

nerdctl can interact with different containerd namespaces, allowing you to manage Docker containers (`moby`), Kubernetes containers (`k8s.io`), or your own custom namespaces.

                # List containers in default namespace
nerdctl ps

# List containers in specific namespace
nerdctl -n moby ps  # Docker containers
nerdctl -n k8s.io ps  # Kubernetes containers

# Set default namespace via environment
export CONTAINERD_NAMESPACE=moby
nerdctl ps

# Create and use custom namespace
nerdctl -n myapp run -d nginx
            

Migrating from Docker to nerdctl

If you're moving from Docker to containerd, nerdctl makes the transition smooth. Most Docker commands work unchanged. Here are some tips for migration:

Use aliases: `alias docker=nerdctl` to use nerdctl with Docker commands
Docker Compose: `nerdctl compose` replaces `docker-compose`
Images: Your existing Docker images are compatible (both use OCI format)
Volumes: Volume mounts work the same way
Networks: Bridge networks are supported

                # Create alias for Docker compatibility
alias docker=nerdctl

# Now you can use docker commands
docker pull nginx:alpine
docker run -d -p 80:80 nginx:alpine
docker ps

# Unalias when needed
unalias docker
            

Frequently Asked Questions

Is nerdctl a complete Docker replacement?

nerdctl covers most Docker CLI commands and features. However, some advanced Docker features (like Swarm mode) are not supported. For most day-to-day container operations, nerdctl is a complete replacement.

Can I use nerdctl with Docker Desktop?

Yes! Docker Desktop includes containerd. Use `nerdctl -n moby` to interact with Docker containers, or set `export CONTAINERD_NAMESPACE=moby`.

Does nerdctl support Docker Compose?

Yes! `nerdctl compose` works with standard docker-compose.yml files. It supports most compose features including networks, volumes, and environment variables.

Is nerdctl production-ready?

Yes, nerdctl is production-ready and used by many organizations. It's actively maintained by the containerd community and follows semantic versioning.

How does nerdctl compare to ctr?

ctr is a low-level debugging tool for containerd internals. nerdctl provides a user-friendly, Docker-like interface. Use nerdctl for daily operations, ctr for debugging.

Can I build images with nerdctl?

Yes! nerdctl supports building images using BuildKit. The `build` command works similarly to Docker build, with support for multi-stage builds, caching, and platforms.

Does nerdctl support Windows containers?

Yes, nerdctl supports Windows containers on Windows hosts with containerd. However, Linux containers remain the primary use case.

How do I update nerdctl?

On Linux, download the latest release from GitHub and replace the binary. On macOS, `brew upgrade nerdctl`. On Windows, use `choco upgrade nerdctl`.

Previous: ctr Commands Next: nerdctl compose

nerdctl brings Docker-like simplicity to containerd. Start using it today for faster, lighter container management.