---

📦 A Practical Guide to ctr Commands in containerd

Containerd’s CLI tool ctr is lightweight, low-level, and mainly used for debugging or advanced operations. This guide organizes the most useful ctr commands topic-wise, with short explanations and real examples.

---

✅ 1. Working With Images

Pulling Images

Pull an image directly from a registry:

$ ctr images pull docker.io/library/nginx:latest

Downloads the nginx latest image into containerd.

Listing Images

List all images available:

$ ctr images ls

Quiet mode (only image names):

$ ctr images ls -q

Removing Images

Delete an image from containerd storage:

$ ctr images rm docker.io/library/golang:latest

Another example:

$ ctr images delete ubuntu:latest

Inspecting Image Metadata

Get full JSON details of an image:

$ ctr image inspect docker.io/redhat/ubi8:8.10

Shows layers, size, config, OS, etc.

Exporting Images

Export a pulled image into a tar file:

$ ctr image export redhat8.10.tar docker.io/redhat/ubi8:8.10

Useful for offline use or transferring to air-gapped servers.

Images Inside a Custom Namespace

List images inside Kubernetes namespace (k8s.io):

$ ctr -n k8s.io images ls -q

Tag an image within a namespace:

$ ctr -n k8s.io images tag docker.io/library/ubuntu:latest ubuntu:latest

---

✅ 2. Managing Namespaces

Namespaces isolate containerd resources (images, containers, tasks).

List Namespaces

$ ctr namespace ls

Create a Namespace

$ ctr namespace create newns

Remove a Namespace

$ ctr namespace rm newns

---

✅ 3. Container & Task Operations

Running a Container

Start a new interactive container:

$ ctr run -t docker.io/library/ubuntu:latest ubu /bin/bash

Run and auto-remove after exit:

$ ctr run --rm -t docker.io/library/ubuntu:latest ubu /bin/bash

The -t option allocates a TTY.

Listing Containers

$ ctr container ls

Example output:

 CONTAINER    IMAGE                              RUNTIME
 ubu          docker.io/library/ubuntu:latest    io.containerd.runc.v2

Starting a Task

Once a container is created, start its task:

$ ctr task start ubu

List running tasks:

$ ctr task ls

---

✅ 4. Full Cleanup Flow (Stopping, Killing, Removing)

This section helps understand the proper deletion sequence.

Step 1: Check Running Tasks

$ ctr task ls

Example:

 TASK    PID        STATUS
 ubu     4087793    RUNNING

Step 2: Check Container

$ ctr container ls

Step 3: Kill the Task

$ ctr task kill --signal SIGKILL ubu

Verify:

$ ctr task ls

Status becomes STOPPED.

Step 4: Remove the Task

$ ctr task rm ubu

You may see:

WARN[0000] task ubu exit with non-zero exit code 137

Safe to ignore the task will be removed.

Step 5: Delete the Container

$ ctr container delete ubu

Check final state:

$ ctr container ls

Should be empty.