containerd CLI

ctr cheatsheet — manage containerd images, containers, namespaces. ctr images pull, ctr run, ctr containers list, ctr tasks. Low-level container runtime reference.

6 min read

What it is

ctr is the command-line client for interacting with the containerd runtime, used for managing containers, images, and other container-related objects directly at the runtime level.

Installation

containerd is typically installed as part of a container runtime environment like Docker or Kubernetes. If you need to install it standalone:

Linux:

# Using apt (Debian/Ubuntu)
sudo apt update
sudo apt install containerd

# Using yum/dnf (CentOS/Fedora/RHEL)
sudo yum install containerd
# or
sudo dnf install containerd

# Enable and start the service
sudo systemctl enable containerd
sudo systemctl start containerd

Mac: containerd is not typically installed directly on macOS. It’s usually managed by higher-level container orchestration tools.

Windows: containerd is not typically installed directly on Windows. It’s usually managed by higher-level container orchestration tools.

Core Concepts

Containerd: The core daemon responsible for managing the container lifecycle, including image transfer, storage, execution, and supervision.
Namespaces: Logical isolation for container objects (containers, images, networks, etc.). default is the default namespace. You can create custom namespaces for better organization (e.g., k8s.io for Kubernetes).
Tasks: The running instance of a container. ctr interacts with tasks to start, stop, and inspect containers.
Containers: The abstract representation of a running instance, defined by its configuration, image, and volumes.
Images: The read-only template used to create containers. ctr can pull, push, save, and list container images.
Snapshots: A copy-on-write filesystem layer that forms the root filesystem of a container.
Content Store: A local cache for downloaded image layers.

Commands / Usage

Managing Namespaces

Namespaces provide isolation for container resources.

List namespaces:
```
ctr namespaces ls
```
List all available namespaces.
Create a namespace:
```
ctr namespaces create myapp-ns
```
Create a new namespace named myapp-ns.
Delete a namespace:
```
ctr namespaces rm myapp-ns
```
Remove the namespace myapp-ns and all its associated resources.

Managing Images

Interact with container images, pulling them from registries and inspecting them.

List images:
```
ctr images ls
```
List all images in the default namespace.
```
ctr -n k8s.io images ls
```
List all images in the k8s.io namespace.
Pull an image:
```
ctr images pull docker.io/library/ubuntu:latest
```
Download the ubuntu:latest image from Docker Hub.

Remove an image:

ctr images rm docker.io/library/ubuntu:latest

Delete the ubuntu:latest image.

Inspect an image:
```
ctr images inspect docker.io/library/ubuntu:latest
```
Show detailed information about the ubuntu:latest image.
Mount an image (for inspection/manual use):
```
ctr images mount docker.io/library/ubuntu:latest /tmp/ubuntu-rootfs
```
Mount the image’s root filesystem to a specified directory.

Unmount an image:

ctr images unmount docker.io/library/ubuntu:latest

Unmount a previously mounted image.

Managing Containers (Tasks)

Create, start, stop, and manage running container instances.

List containers (tasks):
```
ctr tasks ls
```
List all running container tasks in the default namespace.
```
ctr -n k8s.io tasks ls
```
List all running container tasks in the k8s.io namespace.
Create a container:
```
ctr containers create --image docker.io/library/alpine:latest --net-ip 10.0.0.2 my-alpine-container
```
Create a container named my-alpine-container using the alpine:latest image with a specific IP address.
Start a container:
```
ctr tasks start my-alpine-container
```
Start the container named my-alpine-container.
Stop a container:
```
ctr tasks stop my-alpine-container
```
Stop the running container named my-alpine-container.
Delete a container:
```
ctr containers rm my-alpine-container
```
Remove the container definition named my-alpine-container.
Execute a command in a running container:
```
ctr tasks exec --exec-id echo-hello my-alpine-container sh -c 'echo "Hello from container"'
```
Execute a command within the running my-alpine-container. The --exec-id is optional but useful for tracking.
Get container logs:
```
ctr tasks logs my-alpine-container
```
Stream logs from the my-alpine-container.
Inspect a container (task):
```
ctr tasks inspect my-alpine-container
```
Show detailed information about the running task my-alpine-container.
Get container PIDs:
```
ctr tasks pids my-alpine-container
```
List the process IDs associated with the container task.

Managing Snapshots

Manage the filesystem layers used by containers.

List snapshots:
```
ctr snapshots ls
```
List all available snapshots in the default namespace.
Create a snapshot:
```
ctr snapshots create --disconver=false --state=committed my-snapshot-name docker.io/library/alpine:latest
```
Create a snapshot named my-snapshot-name from the alpine:latest image. --disconver=false means it’s not intended to be directly discoverable by ctr images.
Mount a snapshot:
```
ctr snapshots mount my-snapshot-name /tmp/snapshot-rootfs
```
Mount the filesystem of the snapshot my-snapshot-name to a directory.
Unmount a snapshot:
```
ctr snapshots unmount my-snapshot-name
```
Unmount a previously mounted snapshot.
Remove a snapshot:
```
ctr snapshots rm my-snapshot-name
```
Delete the snapshot my-snapshot-name.

Managing Network and Events

Interact with network configurations and event streams.

List network attachments:
```
ctr net attach ls
```
List network attachments for containers.
Get events:
```
ctr events
```
Stream real-time events from containerd. This is useful for monitoring state changes.

Other Utilities

Version:
```
ctr version
```
Display the containerd client and server version information.

Common Patterns

Running a temporary container to execute a command:

# Create a container from an image
ctr containers create --image docker.io/library/ubuntu:latest temp-ubuntu
# Start the container, execute a command, and then stop/remove it
ctr tasks start temp-ubuntu
ctr tasks exec --exec-id run-ls temp-ubuntu sh -c 'ls -l /'
ctr tasks stop temp-ubuntu
ctr containers rm temp-ubuntu

This is a common pattern for running isolated commands or scripts.

Pulling an image and inspecting its layers:

ctr images pull docker.io/library/nginx:latest
ctr images inspect docker.io/library/nginx:latest | jq .

Use jq to pretty-print the JSON output for better readability.

Creating a container from a specific snapshot:

# First, create or have a snapshot available
ctr snapshots create my-custom-snapshot docker.io/library/debian:latest
# Then, create a container using that snapshot as the rootfs
ctr containers create --rootfs my-custom-snapshot my-container-from-snapshot
ctr tasks start my-container-from-snapshot

Monitoring container lifecycle events:
```
ctr events | grep container
```
Filter the event stream to only show container-related events.

Gotchas

Namespace Management: Forgetting to specify the correct namespace (-n <namespace>) can lead to operations failing or affecting the wrong set of resources. Kubernetes, for example, uses the k8s.io namespace.
Container vs. Task: ctr containers create only creates the container definition. You need ctr tasks start to actually run it. Similarly, ctr containers rm removes the definition, while ctr tasks stop stops the running process.
Snapshot Lifecycle: Snapshots are persistent filesystem layers. They are not automatically deleted when a container is removed. You must explicitly use ctr snapshots rm to clean them up, otherwise, they will consume disk space.
Rootless Mode: If containerd is running in rootless mode, certain operations (like creating network interfaces or accessing host resources) might be restricted or require additional configuration.
Image Naming: containerd uses the full image name including the registry (e.g., docker.io/library/ubuntu:latest). Short names like ubuntu might not work directly unless configured in containerd’s config.toml.
ctr vs. docker: ctr operates at a lower level than the docker CLI. It doesn’t have the same user-friendly abstractions for networking, volumes, or build processes. For most day-to-day container tasks, docker or podman are preferred. ctr is more for debugging, low-level control, or integration with custom systems.