nerdctl

contaiNERD CTL - Docker-compatible CLI for containerd, with support for Compose, Rootless, eStargz, OCIcrypt, IPFS, ...

7,892

587

7,892

297

View on GitHub

Top Related Projects

moby

68,457

The Moby Project - a collaborative project for the container ecosystem to assemble container-based systems

cri-tools

1,635

CLI and validation tools for Kubelet Container Runtime Interface (CRI) .

runc

11,728

CLI tool for spawning and running containers according to the OCI specification

podman

22,991

Podman: A tool for managing OCI containers and pods.

Quick Overview

nerdctl is a Docker-compatible CLI for containerd, providing a user-friendly interface for managing containers, images, and other container-related resources. It aims to offer a seamless experience for users familiar with Docker commands while leveraging the power and efficiency of containerd.

Pros

Docker-compatible CLI, allowing easy transition for Docker users
Direct integration with containerd, offering better performance and resource utilization
Support for advanced features like rootless mode and lazy-pulling of images
Active development and community support

Cons

Not a complete drop-in replacement for Docker, some features may be missing or work differently
Requires containerd to be installed and configured separately
May have a steeper learning curve for users new to container technologies
Limited ecosystem compared to Docker's extensive tooling and integrations

Getting Started

To get started with nerdctl, follow these steps:

Install containerd on your system (if not already installed)
Install nerdctl:

# For Linux
wget https://github.com/containerd/nerdctl/releases/download/v1.4.0/nerdctl-1.4.0-linux-amd64.tar.gz
tar Cxzvvf /usr/local/bin nerdctl-1.4.0-linux-amd64.tar.gz

# For macOS
brew install nerdctl

Start using nerdctl with familiar Docker-like commands:

# Pull an image
nerdctl pull nginx

# Run a container
nerdctl run -d -p 8080:80 nginx

# List running containers
nerdctl ps

# Stop and remove a container
nerdctl stop <container_id>
nerdctl rm <container_id>

For more advanced usage and configuration options, refer to the official nerdctl documentation.

Competitor Comparisons

cli

4,831

The Docker CLI

Pros of docker/cli

More mature and widely adopted in the industry
Extensive documentation and community support
Seamless integration with Docker Engine and Docker Hub

Cons of docker/cli

Tightly coupled with Docker Engine, limiting flexibility
Heavier resource footprint compared to nerdctl
Slower development cycle for new features

Code Comparison

nerdctl:

nerdctl run -d --name nginx -p 80:80 nginx
nerdctl ps
nerdctl stop nginx
nerdctl rm nginx

docker/cli:

docker run -d --name nginx -p 80:80 nginx
docker ps
docker stop nginx
docker rm nginx

Key Differences

nerdctl is designed to work with containerd directly, offering a more lightweight solution
docker/cli provides a more comprehensive ecosystem with additional features like Docker Compose
nerdctl aims for compatibility with Docker commands, making it easier for users to transition
docker/cli has better support for legacy systems and a wider range of operating systems
nerdctl focuses on OCI (Open Container Initiative) standards, promoting greater interoperability

Use Cases

Choose docker/cli for established Docker-based workflows and broad compatibility
Opt for nerdctl in Kubernetes environments or when seeking a more lightweight container management tool
Consider nerdctl for projects prioritizing OCI standards and containerd integration

moby

68,457

The Moby Project - a collaborative project for the container ecosystem to assemble container-based systems

Pros of Moby

More mature and established project with a larger community
Broader ecosystem support and integration with Docker-related tools
Extensive documentation and resources available

Cons of Moby

Heavier and more complex architecture
Slower development cycle due to its larger codebase
Tighter coupling with Docker-specific components

Code Comparison

Moby (Docker CLI):

docker run -d --name nginx -p 80:80 nginx
docker ps
docker stop nginx

Nerdctl:

nerdctl run -d --name nginx -p 80:80 nginx
nerdctl ps
nerdctl stop nginx

Key Differences

Nerdctl is designed to be a lightweight, containerd-native alternative to the Docker CLI
Moby provides a full container runtime and management solution, while Nerdctl focuses on CLI interactions with containerd
Nerdctl offers better compatibility with Kubernetes and other cloud-native technologies
Moby includes additional features like Docker Compose and Swarm mode, which are not present in Nerdctl

Use Cases

Choose Moby for traditional Docker workflows and broader ecosystem compatibility
Opt for Nerdctl in Kubernetes environments or when a more lightweight, containerd-focused solution is needed

cri-tools

1,635

CLI and validation tools for Kubelet Container Runtime Interface (CRI) .

Pros of cri-tools

Specifically designed for Kubernetes Container Runtime Interface (CRI)
Provides comprehensive debugging and validation tools for CRI implementations
Officially maintained by the Kubernetes community

Cons of cri-tools

Limited to CRI-specific operations and diagnostics
May have a steeper learning curve for users not familiar with CRI

Code Comparison

cri-tools (crictl):

crictl pull nginx:latest
crictl run nginx.yaml
crictl ps

nerdctl:

nerdctl pull nginx:latest
nerdctl run -d nginx:latest
nerdctl ps

Key Differences

nerdctl offers a Docker-compatible CLI, making it easier for Docker users to transition
cri-tools focuses on CRI-specific operations, while nerdctl provides a broader set of container management features
nerdctl supports both Kubernetes CRI and non-CRI use cases, offering more flexibility

Use Cases

cri-tools: Ideal for Kubernetes cluster administrators and developers working directly with CRI implementations
nerdctl: Suitable for users seeking a Docker-like experience with containerd, including both Kubernetes and non-Kubernetes environments

Community and Ecosystem

cri-tools: Tightly integrated with the Kubernetes ecosystem
nerdctl: Part of the broader containerd project, with growing adoption in various container environments

runc

11,728

CLI tool for spawning and running containers according to the OCI specification

Pros of runc

Lower-level container runtime, providing more direct control over container execution
Lightweight and focused on core container runtime functionality
Widely adopted and supported across various container ecosystems

Cons of runc

Requires more manual configuration and setup compared to higher-level tools
Limited built-in features for container management and orchestration
Steeper learning curve for users new to container technologies

Code Comparison

runc:

spec, err := loadSpec(context.Background(), specConfig)
if err != nil {
    return err
}
status, err := startContainer(context.Background(), spec, opts)

nerdctl:

ctx := namespaces.WithNamespace(context.Background(), namespace)
container, err := client.NewContainer(ctx, id, opts...)
if err != nil {
    return err
}
task, err := container.NewTask(ctx, cio.NewCreator(cio.WithStdio))

Summary

runc is a lower-level container runtime offering more direct control but requiring more manual configuration. nerdctl provides a higher-level interface with additional features for container management. The choice between them depends on the specific use case and desired level of abstraction in container operations.

podman

22,991

Podman: A tool for managing OCI containers and pods.

Pros of Podman

Daemonless architecture, improving security and resource usage
Rootless containers support out-of-the-box
Compatibility with Docker CLI commands and Dockerfiles

Cons of Podman

Less mature ecosystem compared to Docker/containerd
Limited Windows support (primarily focused on Linux)

Code Comparison

Podman:

podman run -d --name nginx -p 8080:80 nginx
podman pod create --name mypod
podman generate systemd --name mypod --files

nerdctl:

nerdctl run -d --name nginx -p 8080:80 nginx
nerdctl compose up -d
nerdctl network create mynetwork

Key Differences

Podman uses a fork/exec model, while nerdctl relies on containerd's API
Podman supports pods natively, whereas nerdctl requires additional setup
nerdctl offers better integration with containerd's existing ecosystem

Use Cases

Podman: Ideal for environments requiring enhanced security and rootless operations
nerdctl: Better suited for users already invested in the containerd ecosystem

Community and Development

Podman: Backed by Red Hat, with a focus on enterprise Linux environments
nerdctl: Developed by the containerd community, with strong ties to Kubernetes

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

[â¬ï¸ Download] [ð Command reference] [âFAQs & Troubleshooting] [ð Additional documents]

nerdctl: Docker-compatible CLI for containerd

logo

nerdctl is a Docker-compatible CLI for containerd.

â Same UI/UX as docker

â Supports Docker Compose (nerdctl compose up)

â [Optional] Supports rootless mode, without slirp overhead (bypass4netns)

â [Optional] Supports lazy-pulling (Stargz, Nydus, OverlayBD)

â [Optional] Supports encrypted images (ocicrypt)

â [Optional] Supports P2P image distribution (IPFS) (*1)

â [Optional] Supports container image signing and verifying (cosign)

nerdctl is a non-core sub-project of containerd.

*1: P2P image distribution (IPFS) is completely optional. Your host is NOT connected to any P2P network, unless you opt in to install and run IPFS daemon.

Examples

Basic usage

To run a container with the default bridge CNI network (10.4.0.0/24):

# nerdctl run -it --rm alpine

To build an image using BuildKit:

# nerdctl build -t foo /some-dockerfile-directory
# nerdctl run -it --rm foo

To build and send output to a local directory using BuildKit:

# nerdctl build -o type=local,dest=. /some-dockerfile-directory

To run containers from docker-compose.yaml:

# nerdctl compose -f ./examples/compose-wordpress/docker-compose.yaml up

Debugging Kubernetes

To list local Kubernetes containers:

# nerdctl --namespace k8s.io ps -a

To build an image for local Kubernetes without using registry:

# nerdctl --namespace k8s.io build -t foo /some-dockerfile-directory
# kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: foo
spec:
  containers:
    - name: foo
      image: foo
      imagePullPolicy: Never
EOF

To load an image archive (docker save format or OCI format) into local Kubernetes:

# nerdctl --namespace k8s.io load < /path/to/image.tar

To read logs (experimental):

# nerdctl --namespace=k8s.io ps -a
CONTAINER ID    IMAGE                                                      COMMAND                   CREATED          STATUS    PORTS    NAMES
...
e8793b8cca8b    registry.k8s.io/coredns/coredns:v1.9.3                     "/coredns -conf /etcâ¦"    2 minutes ago    Up                 k8s://kube-system/coredns-787d4945fb-mfx6b/coredns
...

# nerdctl --namespace=k8s.io logs -f e8793b8cca8b
[INFO] plugin/reload: Running configuration SHA512 = 591cf328cccc12bc490481273e738df59329c62c0b729d94e8b61db9961c2fa5f046dd37f1cf888b953814040d180f52594972691cd6ff41be96639138a43908
CoreDNS-1.9.3
linux/amd64, go1.18.2, 45b0a11
...

Rootless mode

To launch rootless containerd:

$ containerd-rootless-setuptool.sh install

To run a container with rootless containerd:

$ nerdctl run -d -p 8080:80 --name nginx nginx:alpine

See ./docs/rootless.md.

Install

Binaries are available here: https://github.com/containerd/nerdctl/releases

In addition to containerd, the following components should be installed:

CNI plugins: for using nerdctl run.
- v1.1.0 or later is highly recommended.
BuildKit (OPTIONAL): for using nerdctl build. BuildKit daemon (buildkitd) needs to be running. See also the document about setting up BuildKit.
- v0.11.0 or later is highly recommended. Some features, such as pruning caches with nerdctl system prune, do not work with older versions.
RootlessKit and slirp4netns (OPTIONAL): for Rootless mode
- RootlessKit needs to be v0.10.0 or later. v2.0.0 or later is recommended.
- slirp4netns needs to be v0.4.0 or later. v1.1.7 or later is recommended.

These dependencies are included in nerdctl-full-<VERSION>-<OS>-<ARCH>.tar.gz, but not included in nerdctl-<VERSION>-<OS>-<ARCH>.tar.gz.

Brew

On Linux systems you can install nerdctl via brew:

brew install nerdctl

This is currently not supported for macOS. The section below shows how to install on macOS using brew.

macOS

Lima project provides Linux virtual machines for macOS, with built-in integration for nerdctl.

$ brew install lima
$ limactl start
$ lima nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine

FreeBSD

See ./docs/freebsd.md.

Windows

Linux containers: Known to work on WSL2
Windows containers: experimental support for Windows (see below for features that are currently known to work)

Docker

To run containerd and nerdctl inside Docker:

docker build -t nerdctl .
docker run -it --rm --privileged nerdctl

Motivation

The goal of nerdctl is to facilitate experimenting the cutting-edge features of containerd that are not present in Docker (see below).

Note that competing with Docker is not the goal of nerdctl. Those cutting-edge features are expected to be eventually available in Docker as well.

Also, nerdctl might be potentially useful for debugging Kubernetes clusters, but it is not the primary goal.

Features present in `nerdctl` but not present in Docker

Major:

On-demand image pulling (lazy-pulling) using Stargz/Nydus/OverlayBD/SOCI Snapshotter: nerdctl --snapshotter=stargz|nydus|overlaybd|soci run IMAGE .
Image encryption and decryption using ocicrypt (imgcrypt): nerdctl image (encrypt|decrypt) SRC DST
P2P image distribution using IPFS: nerdctl run ipfs://CID . P2P image distribution (IPFS) is completely optional. Your host is NOT connected to any P2P network, unless you opt in to install and run IPFS daemon.
Cosign integration: nerdctl pull --verify=cosign and nerdctl push --sign=cosign, and in Compose
Accelerated rootless containers using bypass4netns: nerdctl run --annotation nerdctl/bypass4netns=true

Minor:

Namespacing: nerdctl --namespace=<NS> ps . (NOTE: All Kubernetes containers are in the k8s.io containerd namespace regardless to Kubernetes namespaces)
Exporting Docker/OCI dual-format archives: nerdctl save .
Importing OCI archives as well as Docker archives: nerdctl load .
Specifying a non-image rootfs: nerdctl run -it --rootfs <ROOTFS> /bin/sh . The CLI syntax conforms to Podman convention.
Connecting a container to multiple networks at once: nerdctl run --net foo --net bar
Running FreeBSD jails.
Better multi-platform support, e.g., nerdctl pull --all-platforms IMAGE
Applying an (existing) AppArmor profile to rootless containers: nerdctl run --security-opt apparmor=<PROFILE>. Use sudo nerdctl apparmor load to load the nerdctl-default profile.
Systemd compatibility support: nerdctl run --systemd=always

Trivial:

Inspecting raw OCI config: nerdctl container inspect --mode=native .

Features implemented in `nerdctl` ahead of Docker

Recursive read-only (RRO) bind-mount: nerdctl run -v /mnt:/mnt:rro (make children such as /mnt/usb to be read-only, too). Requires kernel >= 5.12. The same feature was later introduced in Docker v25 with a different syntax. nerdctl will support Docker v25 syntax too in the future.

Similar tools

ctr: incompatible with Docker CLI, and not friendly to users. Notably, ctr lacks the equivalents of the following nerdctl commands:
- nerdctl run -p <PORT>
- nerdctl run --restart=always --net=bridge
- nerdctl pull with ~/.docker/config.json and credential helper binaries such as docker-credential-ecr-login
- nerdctl logs
- nerdctl build
- nerdctl compose up
crictl: incompatible with Docker CLI, not friendly to users, and does not support non-CRI features
k3c v0.2 (abandoned): needs an extra daemon, and does not support non-CRI features
Rancher Kim (nee k3c v0.3): needs Kubernetes, and only focuses on image management commands such as kim build and kim push
PouchContainer (abandoned?): needs an extra daemon

Developer guide

nerdctl is a containerd non-core sub-project, licensed under the Apache 2.0 license. As a containerd non-core sub-project, you will find the:

information in our containerd/project repository.

Compiling nerdctl from source

Run make && sudo make install.

See the header of go.mod for the minimum supported version of Go.

Using go install github.com/containerd/nerdctl/v2/cmd/nerdctl is possible, but unrecommended because it does not fill version strings printed in nerdctl version

Testing

See testing nerdctl.

Contributing to nerdctl

Lots of commands and flags are currently missing. Pull requests are highly welcome.

Please certify your Developer Certificate of Origin (DCO), by signing off your commit with git commit -s and with your real name.

Command reference

Moved to ./docs/command-reference.md

Additional documents

Configuration guide:

./docs/config.md: Configuration (/etc/nerdctl/nerdctl.toml, ~/.config/nerdctl/nerdctl.toml)
./docs/registry.md: Registry authentication (~/.docker/config.json)

Basic features:

./docs/compose.md: Compose
./docs/rootless.md: Rootless mode
./docs/cni.md: CNI for containers network
./docs/build.md: nerdctl build with BuildKit

Advanced features:

./docs/stargz.md: Lazy-pulling using Stargz Snapshotter
./docs/nydus.md: Lazy-pulling using Nydus Snapshotter
./docs/overlaybd.md: Lazy-pulling using OverlayBD Snapshotter
./docs/ocicrypt.md: Running encrypted images
./docs/gpu.md: Using GPUs inside containers
./docs/multi-platform.md: Multi-platform mode

Experimental features:

./docs/experimental.md: Experimental features
./docs/freebsd.md: Running FreeBSD jails
./docs/ipfs.md: Distributing images on IPFS
./docs/builder-debug.md: Interactive debugging of Dockerfile

Implementation details:

./docs/dir.md: Directory layout (/var/lib/nerdctl)

Misc:

./docs/faq.md: FAQs and Troubleshooting

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Getting Started

Competitor Comparisons

Pros of docker/cli

Cons of docker/cli

Code Comparison

Key Differences

Use Cases

Pros of Moby

Cons of Moby

Code Comparison

Key Differences

Use Cases

Pros of cri-tools

Cons of cri-tools

Code Comparison

Key Differences

Use Cases

Community and Ecosystem

Pros of runc

Cons of runc

Code Comparison

Summary

Pros of Podman

Cons of Podman

Code Comparison

Key Differences

Use Cases

Community and Development

Convert designs to code with AI

README

nerdctl: Docker-compatible CLI for containerd

Examples

Basic usage

Debugging Kubernetes

Rootless mode

Install

Brew

macOS

FreeBSD

Windows

Docker

Motivation

Features present in nerdctl but not present in Docker

Features implemented in nerdctl ahead of Docker

Similar tools

Developer guide

Compiling nerdctl from source

Testing

Contributing to nerdctl

Command reference

Additional documents

Top Related Projects

Convert designs to code with AI

Features present in `nerdctl` but not present in Docker

Features implemented in `nerdctl` ahead of Docker