Installing containerd

Ubuntu / Debian CentOS / RHEL macOS Windows

Step-by-step guide to install containerd on all major operating systems. Learn configuration, verification, and basic container operations.

Ubuntu/Debian CentOS/RHEL macOS Windows

Quick Navigation

Ubuntu / Debian

CentOS / RHEL

macOS

Windows

Installing containerd on Ubuntu / Debian

                # Update package repository
sudo apt-get update

# Install containerd from official repository
sudo apt-get install -y containerd

# Or install from Docker repository (newer version)
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y containerd.io

# Start and enable containerd service
sudo systemctl enable containerd
sudo systemctl start containerd

# Verify installation
sudo systemctl status containerd
containerd --version
            

Installing containerd on CentOS / RHEL

                # Install containerd from official repository
sudo yum install -y containerd

# Or install from Docker repository (CentOS 7/8/9)
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y containerd.io

# Start and enable containerd service
sudo systemctl enable containerd
sudo systemctl start containerd

# Verify installation
sudo systemctl status containerd
containerd --version

# For RHEL-based systems with SELinux
sudo setsebool -P container_manage_cgroup on
            

Installing containerd on macOS

                # Using Homebrew
brew install containerd

# Or using nerdctl (includes containerd)
brew install nerdctl

# Start containerd (macOS doesn't use systemd)
# containerd runs as a background process
containerd &

# Verify installation
containerd --version
nerdctl --version  # if installed

# For Lima VM (recommended for full containerd experience)
brew install lima
limactl start template://containerd
limactl shell containerd
            

On macOS, containerd runs in a Linux VM. For the best experience, use Lima or Docker Desktop (which includes containerd).

Installing containerd on Windows

                # Using Chocolatey
choco install containerd

# Download from GitHub releases (manual)
# Visit: https://github.com/containerd/containerd/releases
# Download containerd-<version>-windows-amd64.tar.gz

# Extract and add to PATH

# Install as Windows service
containerd --config config.toml

# Using WSL2 (recommended for Linux containers)
# Install Docker Desktop with WSL2 backend
# Docker Desktop includes containerd

# For native Windows containers
# Enable Containers feature in Windows Features
            

Windows containers require Windows Server 2019 or Windows 10 Pro/Enterprise. For Linux containers on Windows, use WSL2.

Post-Installation Configuration

                # Generate default configuration file
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

# For Kubernetes CRI (important for K8s nodes)
# Edit /etc/containerd/config.toml
# Set SystemdCgroup = true for better cgroup management

sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml

# Configure registry mirrors (optional)
# Add to config.toml:
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
  endpoint = ["https://registry-1.docker.io"]

# Restart containerd after configuration changes
sudo systemctl restart containerd

# Test pulling an image
sudo ctr image pull docker.io/library/hello-world:latest
sudo ctr run --rm docker.io/library/hello-world:latest test
            

Verifying containerd Installation

                # Check containerd version
containerd --version

# Check containerd service status (Linux)
sudo systemctl status containerd

# List containerd namespaces
sudo ctr namespace ls

# Pull and run a test container
sudo ctr image pull docker.io/library/alpine:latest
sudo ctr run --rm docker.io/library/alpine:latest test echo "containerd is working!"

# Check containerd configuration
sudo containerd config dump

# For Kubernetes nodes, test CRI
sudo crictl info
sudo crictl ps
            

If you see "containerd is working!" message, your installation is successful!

Installing nerdctl (Docker-compatible CLI)

nerdctl provides a Docker-like experience for containerd, making it easier for Docker users to transition.

                # Install nerdctl on Linux
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 nerdctl on macOS
brew install nerdctl

# Test nerdctl
nerdctl version
nerdctl pull nginx:alpine
nerdctl run -d -p 80:80 --name web nginx:alpine
nerdctl ps
nerdctl logs web
nerdctl stop web
nerdctl rm web

# nerdctl compose support
nerdctl compose up -d
nerdctl compose down
            

Troubleshooting Common Issues

                # Issue: "failed to dial /run/containerd/containerd.sock"
# Solution: Start containerd service
sudo systemctl start containerd

# Issue: Permission denied (Linux)
# Solution: Add user to containerd group or use sudo
sudo usermod -aG containerd $USER
# Log out and back in

# Issue: cgroup v2 not supported
# Check cgroup version
mount | grep cgroup2
# For older systems, enable cgroup v2 in kernel parameters

# Issue: Port conflicts on macOS
# Solution: Use different ports or stop conflicting services

# Check containerd logs
sudo journalctl -u containerd -f

# Reset containerd (dangerous - removes all data)
sudo systemctl stop containerd
sudo rm -rf /var/lib/containerd
sudo systemctl start containerd
            

Frequently Asked Questions

Does Docker Desktop already include containerd?

Yes! Docker Desktop includes containerd as its underlying runtime. You don't need to install containerd separately if you have Docker Desktop.

What's the difference between containerd and Docker Engine?

containerd is a runtime-only component. Docker Engine includes containerd plus additional features like build, CLI, and Compose. containerd is lighter and more focused.

Can I use containerd with Kubernetes?

Absolutely! containerd is the default and recommended runtime for Kubernetes v1.24+. It implements the CRI (Container Runtime Interface) natively.

How do I uninstall containerd?

On Ubuntu: `sudo apt-get remove containerd`. On CentOS: `sudo yum remove containerd`. On macOS: `brew uninstall containerd`. Also remove `/var/lib/containerd` to delete data.

Do I need to install runc separately?

No, containerd includes runc as a dependency. When you install containerd, runc is installed automatically.

Why does my containerd service fail to start?

Check logs with `journalctl -u containerd -f`. Common causes: port conflicts, configuration errors, or missing dependencies.

Previous: containerd vs Docker Next: ctr Commands

containerd is the foundation of modern container infrastructure. Install it today and start exploring container runtime capabilities.