ctr Commands

Debugging Low-Level Ops Native CLI

`ctr` is the native containerd CLI tool for debugging, low-level operations, and advanced container management. Learn essential commands for container, image, snapshot, and namespace management.

Container Ops Image Ops Snapshot Ops Namespace Ops

What is ctr?

`ctr` is the native command-line interface for containerd. It provides direct access to containerd's core functionality without any abstraction layer. Unlike Docker or nerdctl, `ctr` is designed for debugging, troubleshooting, and low-level operations.

While `ctr` is powerful, it's not meant for day-to-day container management. For regular use, consider `nerdctl` which provides a Docker-like experience. Use `ctr` when you need to debug containerd internals or perform operations that aren't exposed through higher-level tools.

`ctr` is extremely useful for debugging Kubernetes nodes when you need to inspect containers directly without using `kubectl` or `crictl`.

Global Options

                # ctr global options
ctr --help

# Common global flags:
-n, --namespace           # Specify namespace (default: "default")
-a, --address             # containerd socket address
--timeout                 # Command timeout
--debug                   # Enable debug logging
--config                  # Config file path

# Examples
ctr -n k8s.io container ls
ctr --debug image pull nginx:alpine
ctr --address /run/containerd/containerd.sock image ls
            

Container Commands

ctr container create

Create a container (without starting)

ctr container delete

Delete a container

ctr container info

Show container details

ctr container ls

List containers

ctr container label

Manage container labels

                # Create a container
ctr container create docker.io/library/nginx:alpine nginx

# List containers
ctr container ls

# Get container info
ctr container info nginx

# Delete container
ctr container delete nginx

# Create with options
ctr container create --env VAR=value --label app=web docker.io/library/nginx:alpine nginx
            

Task Commands

ctr task start

Start a container task

ctr task pause

Pause a running task

ctr task resume

Resume a paused task

ctr task kill

Kill a task process

ctr task ps

List processes in a task

ctr task ls

List all tasks

ctr task exec

Execute command in task

                # Start a task from a container
ctr task start nginx

# List tasks
ctr task ls

# Pause/resume task
ctr task pause nginx
ctr task resume nginx

# Execute command in running task
ctr task exec nginx sh -c "echo hello"

# Kill task
ctr task kill nginx

# Run container directly (create + start)
ctr run --rm docker.io/library/alpine:latest test echo "Hello"
            

Image Commands

ctr image pull

Pull image from registry

ctr image push

Push image to registry

ctr image ls

List images

ctr image rm

Remove image

ctr image tag

Tag an image

ctr image export

Export image to tar

ctr image import

Import image from tar

ctr image info

Show image details

                # Pull image
ctr image pull docker.io/library/nginx:alpine

# List images
ctr image ls

# Tag image
ctr image tag docker.io/library/nginx:alpine myregistry/nginx:alpine

# Push image
ctr image push myregistry/nginx:alpine

# Remove image
ctr image rm docker.io/library/nginx:alpine

# Export/import image
ctr image export nginx.tar docker.io/library/nginx:alpine
ctr image import nginx.tar

# Image info
ctr image info docker.io/library/nginx:alpine
            

Content Commands

ctr content ls

List content blobs

ctr content info

Show content details

ctr content rm

Delete content

ctr content prune

Clean up unused content

ctr content fetch

Fetch content from registry

                # List content
ctr content ls

# Get content info
ctr content info sha256:a1b2c3d4e5f6...

# Delete content
ctr content rm sha256:a1b2c3d4e5f6...

# Prune unused content
ctr content prune

# Fetch specific blob
ctr content fetch docker.io/library/nginx:alpine@sha256:abc123...
            

Snapshot Commands

ctr snapshot ls

List snapshots

ctr snapshot usage

Show snapshot usage

ctr snapshot rm

Remove snapshot

ctr snapshot mount

Mount snapshot

ctr snapshot info

Snapshot details

                # List snapshots
ctr snapshot ls

# Snapshot usage
ctr snapshot usage

# Remove snapshot
ctr snapshot rm 

# Mount snapshot for inspection
ctr snapshot mount  /mnt
# ... inspect /mnt ...
ctr snapshot unmount /mnt
            

Namespace Commands

ctr namespace ls

List namespaces

ctr namespace create

Create namespace

ctr namespace rm

Delete namespace

ctr namespace label

Manage namespace labels

                # List namespaces
ctr namespace ls

# Create namespace
ctr namespace create myapp

# Delete namespace (removes all resources)
ctr namespace rm myapp

# Namespace labels
ctr namespace label myapp environment=production
            

Plugin Commands

                # List loaded plugins
ctr plugin ls

# Plugin info
ctr plugin info io.containerd.runtime.v2.task

# Plugin capabilities
ctr plugin capabilities
            

Version and Info Commands

                # Show containerd version
ctr version
ctr version --details

# Show containerd info
ctr info

# Show event stream
ctr events

# Show system info
ctr system info
            

ctr vs nerdctl: When to Use Which

ctr: Use for debugging, low-level operations, investigating containerd internals, and when `nerdctl` isn't available.
nerdctl: Use for day-to-day container management, Docker-like experience, and when you need Compose support.

                # ctr is minimal and lower-level
ctr image pull docker.io/library/nginx:alpine
ctr run --rm docker.io/library/nginx:alpine test nginx -g "daemon off;"

# nerdctl is Docker-like and user-friendly
nerdctl pull nginx:alpine
nerdctl run -d -p 80:80 --name web nginx:alpine
            

Frequently Asked Questions

Why use ctr instead of Docker or nerdctl?

`ctr` is the native containerd CLI for debugging and low-level operations. It gives you direct access to containerd internals that higher-level tools don't expose. Use it for troubleshooting containerd issues.

Can I use ctr to manage Docker containers?

Yes! Docker containers run in the `moby` namespace. Use `ctr -n moby container ls` to see Docker containers from the containerd perspective.

What is the default namespace for ctr?

The default namespace is `default`. Use `-n` flag to specify a different namespace like `moby` (Docker) or `k8s.io` (Kubernetes).

How do I get an interactive shell with ctr?

Use `ctr run --rm -t docker.io/library/alpine:latest test sh` to start an interactive shell. The `-t` flag allocates a pseudo-TTY.

Can I use ctr with containerd running on a remote host?

Yes! Use the `--address` flag to specify the containerd socket path. For remote, you need to tunnel the socket via SSH or use a remote containerd endpoint.

What's the difference between `ctr container` and `ctr task`?

A container is the configuration (like a stopped VM). A task is the running process inside the container. You create a container, then start a task to run it.

How do I view logs with ctr?

`ctr` doesn't have a built-in `logs` command like Docker. Use `ctr task ls` to find the task, then view logs via the container's output or `ctr task exec` to inspect.

Is ctr production-safe?

Yes, `ctr` is safe to use in production for debugging. However, it's a low-level tool and commands can be destructive. Always double-check commands before executing.

Previous: Content Store & Image Management Next: nerdctl Guide

Master `ctr` commands to debug containerd issues, inspect container internals, and perform low-level operations with confidence.