containerd Cheatsheet
A comprehensive quick reference for containerd commands, configuration, and troubleshooting. Keep this cheatsheet handy for daily container runtime operations.
ctr
crictl
nerdctl
Config
Quick Navigation
ctr: The Native containerd CLI
ctr is the native CLI for containerd. It provides low-level access to containerd's functionality. Use it for debugging and troubleshooting.
Service Management
systemctl status containerd
Check containerd daemon status
sudo systemctl status containerd
systemctl start containerd
Start containerd daemon
sudo systemctl start containerd
systemctl stop containerd
Stop containerd daemon
sudo systemctl stop containerd
systemctl restart containerd
Restart containerd daemon
sudo systemctl restart containerd
systemctl enable containerd
Enable containerd to start at boot
sudo systemctl enable containerd
Namespace Management
ctr namespace ls
List all namespaces
ctr namespace ls
ctr namespace create <name>
Create a new namespace
ctr namespace create my-namespace
ctr namespace rm <name>
Remove a namespace
ctr namespace rm my-namespace
ctr -n <namespace> ...
Specify namespace for commands (default: default)
ctr -n k8s.io image ls
ctr: Image Management
Listing and Inspecting Images
ctr image ls
List all images
ctr image ls
ctr image ls -q
List only image names (quiet mode)
ctr image ls -q
ctr image info <image>
Show detailed image information
ctr image info docker.io/nginx:latest
ctr image list-platforms
List platforms supported by an image
ctr image list-platforms docker.io/nginx:latest
Pulling and Pushing Images
ctr image pull <image>
Pull an image from registry
ctr image pull docker.io/nginx:latest
ctr image pull --debug <image>
Pull with debug output for troubleshooting
ctr image pull --debug docker.io/nginx:latest
ctr image pull --user <user:pass> <image>
Pull with authentication
ctr image pull --user admin:secret myregistry.io/app:latest
ctr image pull --platform <platform> <image>
Pull image for specific platform
ctr image pull --platform linux/arm64 docker.io/nginx:latest
ctr image push <image>
Push an image to registry
ctr image push myregistry.io/app:latest
Removing and Pruning Images
ctr image rm <image>
Remove an image
ctr image rm docker.io/nginx:latest
ctr image prune
Remove unused images (prompts for confirmation)
ctr image prune
ctr image prune --keep=5
Keep the 5 most recently used images
ctr image prune --keep=5
ctr image prune -f
Force prune without confirmation
ctr image prune -f
ctr: Container Management
Listing and Inspecting Containers
ctr container ls
List all containers
ctr container ls
ctr container ls -q
List only container IDs
ctr container ls -q
ctr container info <id>
Show detailed container information
ctr container info my-container
ctr container metrics <id>
Show container resource metrics
ctr container metrics my-container
Creating and Running Containers
ctr container create <image> <name>
Create a container without starting it
ctr container create docker.io/nginx:latest my-nginx
ctr task start <id>
Start a container task
ctr task start my-nginx
ctr run <image> <name> <command>
Create and start a container in one command
ctr run docker.io/alpine:latest alpine sh -c "echo Hello"
ctr run --rm <image> <name> <command>
Run container and remove after exit
ctr run --rm docker.io/alpine:latest alpine echo Hello
ctr run --tty --stdin <image> <name> <command>
Run with interactive TTY
ctr run --tty --stdin docker.io/alpine:latest alpine /bin/sh
Managing Running Containers
ctr task ls
List running tasks (containers)
ctr task ls
ctr task kill <id> <signal>
Send signal to a container
ctr task kill my-nginx SIGTERM
ctr task pause <id>
Pause a container
ctr task pause my-nginx
ctr task resume <id>
Resume a paused container
ctr task resume my-nginx
ctr task delete <id>
Delete a container task
ctr task delete my-nginx
ctr container rm <id>
Remove a container (must be stopped)
ctr container rm my-nginx
Container Logs
ctr task logs <id>
View container logs
ctr task logs my-nginx
ctr task logs -f <id>
Follow container logs
ctr task logs -f my-nginx
ctr task logs --tail=50 <id>
View last 50 log lines
ctr task logs --tail=50 my-nginx
Executing Commands
ctr task exec <id> <command>
Execute a command in a running container
ctr task exec my-nginx /bin/sh -c "echo test"
ctr task exec --tty --stdin <id> <command>
Execute with interactive TTY
ctr task exec --tty --stdin my-nginx /bin/sh
ctr: Snapshot Management
ctr snapshot ls
List all snapshots
ctr snapshot ls
ctr snapshot prune
Remove unused snapshots
ctr snapshot prune
ctr snapshot prune -f
Force prune without confirmation
ctr snapshot prune -f
ctr content prune
Remove orphaned content blobs
ctr content prune
ctr content prune -f
Force content prune without confirmation
ctr content prune -f
crictl: Kubernetes Container Debugging
crictl is the CRI-compatible CLI for Kubernetes debugging. Use it to inspect pods and containers on Kubernetes nodes.
Pod and Container Management
crictl pods
List all pods
crictl pods
crictl pods --namespace <ns>
List pods in a specific namespace
crictl pods --namespace default
crictl pods --name <name>
List pods with specific name
crictl pods --name nginx
crictl ps
List running containers
crictl ps
crictl ps -a
List all containers (including stopped)
crictl ps -a
crictl ps --state Exited
List exited containers
crictl ps --state Exited
crictl inspect <id>
Show detailed container information
crictl inspect abc123
crictl inspectp <pod-id>
Show detailed pod information
crictl inspectp abc123
Image Management
crictl images
List all images
crictl images
crictl images -v
List images with detailed information
crictl images -v
crictl rmi <image>
Remove an image
crictl rmi nginx:latest
crictl rmi --prune
Remove unused images
crictl rmi --prune
crictl pull <image>
Pull an image
crictl pull nginx:latest
Debugging Commands
crictl logs <container-id>
View container logs
crictl logs abc123
crictl logs -f <container-id>
Follow container logs
crictl logs -f abc123
crictl logs --tail=50 <container-id>
View last 50 log lines
crictl logs --tail=50 abc123
crictl exec -it <container-id> <command>
Execute command in container
crictl exec -it abc123 /bin/sh
crictl stats
Show resource usage statistics
crictl stats
crictl events
Show container events
crictl events
crictl version
Show crictl and runtime versions
crictl version
nerdctl: Docker-Compatible CLI
nerdctl provides a Docker-compatible experience for containerd. Use it for development and when you need Docker-like commands.
Common Commands
nerdctl images
List images (like docker images)
nerdctl images
nerdctl ps -a
List all containers (like docker ps -a)
nerdctl ps -a
nerdctl pull <image>
Pull an image (like docker pull)
nerdctl pull nginx:latest
nerdctl run <image>
Run a container (like docker run)
nerdctl run -d --name my-nginx nginx
nerdctl run --rm <image>
Run and remove on exit
nerdctl run --rm alpine echo Hello
nerdctl exec -it <container> <command>
Execute command in container
nerdctl exec -it my-nginx /bin/sh
nerdctl logs -f <container>
Follow container logs
nerdctl logs -f my-nginx
nerdctl stop <container>
Stop a container
nerdctl stop my-nginx
nerdctl start <container>
Start a container
nerdctl start my-nginx
nerdctl rm <container>
Remove a container
nerdctl rm my-nginx
nerdctl rmi <image>
Remove an image
nerdctl rmi nginx:latest
nerdctl system prune
Remove unused data (like docker system prune)
nerdctl system prune -f
Compose Commands
nerdctl compose up -d
Start services in background
nerdctl compose up -d
nerdctl compose down
Stop and remove services
nerdctl compose down
nerdctl compose logs -f
Follow compose logs
nerdctl compose logs -f
nerdctl compose exec <service> <command>
Execute command in service
nerdctl compose exec web /bin/sh
Configuration Quick Reference
config.toml Essentials
containerd config default > /etc/containerd/config.toml
Generate default configuration
containerd config default | sudo tee /etc/containerd/config.toml
containerd config dump
Dump current active configuration
containerd config dump
containerd config validate
Validate configuration syntax
containerd config validate
Key Configuration Settings
log_level = "info"
Set log level (trace, debug, info, warn, error, fatal, panic)
snapshotter = "overlayfs"
Choose snapshot driver (overlayfs, native, zfs, btrfs)
SystemdCgroup = true
Enable systemd cgroup management (required for cgroup v2)
sandbox_image = "registry.k8s.io/pause:3.9"
Set Kubernetes pause image
image_pull_progress_timeout = "120s"
Set image pull timeout
Registry Configuration
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
Configure Docker Hub mirror
endpoint = ["https://mirror.gcr.io"]
[plugins."io.containerd.grpc.v1.cri".registry.configs."myregistry.io".auth]
Configure registry authentication
username = "user"
password = "pass"
[plugins."io.containerd.grpc.v1.cri".registry.configs."myregistry.io".tls]
Configure registry TLS settings
insecure_skip_verify = false
Metrics Configuration
[metrics]
Enable metrics endpoint
address = "0.0.0.0:1338"
enabled = true
[metrics.prometheus]
Enable Prometheus metrics format
enabled = true
Troubleshooting Quick Reference
Diagnostic Commands
journalctl -u containerd -f
Follow containerd logs
journalctl -u containerd -n 50
View last 50 log lines
journalctl -u containerd --since "1 hour ago"
View logs from last hour
journalctl -u containerd | grep -i error
Find errors in logs
sudo systemctl status containerd
Check containerd status
sudo lsof /run/containerd/containerd.sock
Check socket usage
sudo strace -p $(pidof containerd)
Trace containerd system calls
Common Issues & Fixes
ctr image pull --debug <image>
Debug image pull failures
curl -v https://registry-1.docker.io/v2/
Test registry connectivity
nslookup registry-1.docker.io
Check DNS resolution
df -h /var/lib/containerd
Check disk space
df -i /var/lib/containerd
Check inode usage
du -sh /var/lib/containerd/* | sort -h
Find large directories
cat /proc/sys/user/max_user_namespaces
Check user namespace support
mount | grep cgroup2
Check cgroup version
sestatus
Check SELinux status
sudo aa-status
Check AppArmor status
Logs & Metrics Quick Reference
Log Locations
/var/lib/containerd/
containerd root directory (persistent data)
/var/log/containers/
Container logs (Kubernetes)
/var/lib/containerd/io.containerd.content.v1.content/
Content store (image blobs)
/var/lib/containerd/io.containerd.snapshotter.v1.overlayfs/
Snapshot store
/run/containerd/containerd.sock
containerd socket
Metrics Endpoints
curl http://localhost:1338/metrics
View Prometheus metrics
curl http://localhost:1338/metrics | grep container_runtime
Filter container runtime metrics
curl http://localhost:1338/metrics | grep container_image
Filter image-related metrics
Frequently Asked Questions
What's the difference between ctr, crictl, and nerdctl?
ctr is the native containerd CLI for low-level debugging. crictl is for Kubernetes pod/container debugging using CRI. nerdctl provides a Docker-compatible experience. Use ctr for direct containerd access, crictl for Kubernetes nodes, and nerdctl for development.
When should I use ctr instead of crictl?
Use ctr when you need low-level containerd access or when debugging containerd itself. Use crictl for Kubernetes container debugging as it understands pod sandboxes and CRI concepts. For Kubernetes nodes, crictl is preferred.
How do I specify a namespace in ctr?
Use the
-n flag: ctr -n k8s.io image ls. The default namespace is "default". The Kubernetes CRI plugin uses the "k8s.io" namespace. Why can't I see my Kubernetes containers with ctr?
Kubernetes containers are in the "k8s.io" namespace. Use
ctr -n k8s.io container ls or ctr -n k8s.io task ls to see them. For simpler debugging, use crictl ps -a. How do I check containerd version?
Use
containerd --version or ctr version. For Kubernetes nodes, crictl version shows both crictl and containerd versions. What's the quickest way to free disk space?
Run
ctr image prune -f to remove unused images, then ctr snapshot prune -f and ctr content prune -f. For Kubernetes nodes, use crictl rmi --prune. How do I debug a container that won't start?
Check containerd logs with
journalctl -u containerd -f. Use crictl logs <container-id> for container logs. Check runc with runc --version. Verify SystemdCgroup = true in config.toml. Check SELinux/AppArmor policies. Where can I find more containerd resources?
Check the official containerd documentation (github.com/containerd/containerd), the containerd blog, and community resources. The
containerd GitHub repository has extensive documentation and examples.Keep this cheatsheet handy for quick reference during daily containerd operations. Bookmark it for easy access.