nerdctl README

The project's README from github.com/containerd/nerdctl. As one markdown file: README.md.

[⬇️ 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

See also ./examples/compose-wordpress.

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:

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

Windows

Install with Scoop:

scoop install nerdctl

Regarding compatibility, note that:

FreeBSD

See ./docs/freebsd.md.

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:

Minor:

Trivial:

Features implemented in nerdctl ahead of Docker

Similar tools

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:

Basic features:

Advanced features:

Experimental features:

Implementation details:

Misc:

nerdctl (containerd/nerdctl)

Searching Database…

10.4K ·GitHub
Nerdctl
这是什么？nerdctl 是一个兼容 Docker 的 containerd 命令行客户端。它沿用 Docker 式的命令界面和使用体验，同时提供 Docker 没有的 containerd 专有功能。
它是 docker 命令行的替代品，还是和它一起运行的工具？它是一个独立的命令行二进制程序（nerdctl 命令），直接与 containerd 通信。它的命令和参数与 Docker 保持一致，因此你可以把 docker 命令换成对应的 'nerdctl run' 或 'nerdctl compose up' 等命令。
我该如何安装并开始使用？可以下载预编译的二进制文件（完整版或精简版 tar.gz 压缩包），也可以在 Linux 上通过 Homebrew、在 Windows 上通过 Scoop、在 macOS 上通过 Lima 安装（Lima 会在 Linux 虚拟机中运行它）；也可以用 'make && sudo make install' 从源码自行编译。
我需要先运行 containerd 吗，还是 nerdctl 自带守护进程？nerdctl 只是客户端，需要有正在运行的 containerd 守护进程（如果使用 rootless 模式，则需要 rootless containerd 实例）。如果你不想单独安装 containerd，也可以在 Docker 中同时运行 containerd 和 nerdctl。
它在 macOS 和 Windows 上的表现和在 Linux 上一样吗？完整的原生支持仅限 Linux。在 macOS 上需要 Lima 来运行 Linux 虚拟机；在 Windows 上，可以通过 WSL2 运行 Linux 容器，而原生 Windows 容器支持仍处于实验阶段。
谁会选择用它代替 Docker？想要体验 containerd 前沿功能的开发者会选择它，这些功能包括按需拉取（lazy-pulling）、镜像加密、IPFS 分发以及 Kubernetes 容器调试，而这些目前在 Docker 中尚不可用。同时，他们仍能保持熟悉的类 Docker 操作界面。
如果我不想使用任何 P2P 网络，IPFS 支持会被强制开启吗？不会。基于 IPFS 的镜像分发完全需要用户主动开启；除非你刻意安装并运行 IPFS 守护进程，否则你的机器不会连接到任何 P2P 网络。
我能通过 nerdctl 让容器使用 GPU 吗？可以，官方有专门的文档介绍如何在 nerdctl 运行的容器中使用 GPU。
nerdctl 提供了哪些 Docker 不具备的 containerd 专有功能？支持通过 Stargz、Nydus、OverlayBD 或 SOCI 快照器实现按需拉取镜像；支持使用 ocicrypt 进行镜像加密和解密；支持使用 cosign 对镜像进行签名和验证；支持通过 bypass4netns 加速 rootless 网络；还支持让一个容器同时连接多个网络。
nerdctl 能帮我调试 Kubernetes 容器吗？可以。你可以用 nerdctl 列出、构建和加载本地 Kubernetes 集群所用的镜像，也可以读取容器日志，因为所有 Kubernetes 容器都位于 k8s.io containerd 命名空间中。
nerdctl 与 containerd 自带的 ctr 或 crictl 工具相比有何不同？与 ctr 和 crictl 不同，nerdctl 兼容 Docker 命令行，而且更易上手。它支持端口发布、重启策略、构建、日志以及 Docker Compose 等功能，而 ctr 和 crictl 都不提供这些。
nerdctl 支持 Docker Compose 文件吗？支持。它实现了 'nerdctl compose up' 及相关命令，可直接基于 containerd 运行 docker-compose.yaml 文件。
What are similar projects?containerd, lima, skopeo, compose, podman, colima, harbor, public-image-mirror
Which topics is it in?containerd, registry, p2p, containers, compiler, orchestration, encryption, kubernetes, devops, go, command-line-tool, security
Creator
containerd
Size
15 MB
Stars
10.4K
Updated
CommitOct 16Releasev2.4.1Oct 02
Age
5y
Commits · 90 Days