[⬇️ 下载] [📖 命令参考] [❓常见问题与故障排除] [📚 其他文档]

nerdctl: 用于containerd的Docker兼容CLI

nerdctl是一个与Docker兼容的CLI，用于containerd。

✅ 与docker相同的UI/UX

✅ 支持Docker Compose（nerdctl compose up）

✅ [可选] 支持无根模式，无slirp开销（bypass4netns）

✅ [可选] 支持延迟拉取（Stargz、Nydus、OverlayBD）

✅ [可选] 支持加密镜像（ocicrypt）

✅ [可选] 支持P2P镜像分发（IPFS） (*1)

✅ [可选] 支持容器镜像签名和验证（cosign）

nerdctl是containerd的一个非核心子项目。

*1：P2P镜像分发（IPFS）完全是可选的。除非您选择安装并运行IPFS守护进程，否则您的主机不会连接到任何P2P网络。

示例

基本用法

使用默认的bridge CNI网络（10.4.0.0/24）运行容器：

# nerdctl run -it --rm alpine

使用BuildKit构建镜像：

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

使用BuildKit构建并将输出发送到本地目录：

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

从docker-compose.yaml运行容器：

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

另请参阅./examples/compose-wordpress。

调试Kubernetes

列出本地Kubernetes容器：

# nerdctl --namespace k8s.io ps -a

为本地Kubernetes构建镜像，无需使用镜像仓库：

# 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

将镜像归档（docker save格式或OCI格式）加载到本地Kubernetes：

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

读取日志（实验性）：

# 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
...

无根模式

启动无根containerd：

$ containerd-rootless-setuptool.sh install

使用无根containerd运行容器：

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

参见./docs/rootless.md。

安装

可以在这里下载二进制文件：https://github.com/containerd/nerdctl/releases

除了containerd之外，还应安装以下组件：

• CNI插件：用于使用nerdctl run。
  • 强烈建议使用v1.1.0或更高版本。
• BuildKit（可选）：用于使用nerdctl build。需要运行BuildKit守护进程（buildkitd）。另请参阅有关设置BuildKit的文档。
  • 强烈建议使用v0.11.0或更高版本。某些功能，如使用nerdctl system prune清理缓存，在旧版本中不起作用。
• RootlessKit和slirp4netns（可选）：用于无根模式
  • RootlessKit需要v0.10.0或更高版本。建议使用v2.0.0或更高版本。
  • slirp4netns需要v0.4.0或更高版本。建议使用v1.1.7或更高版本。

这些依赖项包含在nerdctl-full-<VERSION>-<OS>-<ARCH>.tar.gz中，但不包含在nerdctl-<VERSION>-<OS>-<ARCH>.tar.gz中。

Brew

在Linux系统上，您可以通过brew安装nerdctl：

brew install nerdctl

目前不支持macOS。下面的部分展示了如何使用brew在macOS上安装。

macOS

Lima项目为macOS提供了Linux虚拟机，内置了nerdctl集成。

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

FreeBSD

参见./docs/freebsd.md。

Windows

• Linux容器：已知在WSL2上可以工作
• Windows容器：对Windows的实验性支持（请参阅下面目前已知可用的功能）

Docker

在Docker内运行containerd和nerdctl：

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

动机

nerdctl的目标是方便实验containerd中存在但Docker中不存在的前沿功能（见下文）。

请注意，与Docker竞争并不是nerdctl的目标。预计这些前沿功能最终也会在Docker中可用。

此外，nerdctl可能对调试Kubernetes集群有潜在用途，但这不是主要目标。

nerdctl中存在但Docker中不存在的功能

主要功能：

• 使用Stargz/Nydus/OverlayBD/SOCI Snapshotter进行按需镜像拉取（延迟拉取）：nerdctl --snapshotter=stargz|nydus|overlaybd|soci run IMAGE。
• 使用ocicrypt（imgcrypt）进行镜像加密和解密：nerdctl image (encrypt|decrypt) SRC DST
• 使用IPFS进行P2P镜像分发：nerdctl run ipfs://CID。 P2P镜像分发（IPFS）完全是可选的。除非您选择安装并运行IPFS守护进程，否则您的主机不会连接到任何P2P网络。
• Cosign集成：nerdctl pull --verify=cosign和nerdctl push --sign=cosign，以及在Compose中使用
• 使用bypass4netns加速无根容器：nerdctl run --annotation nerdctl/bypass4netns=true

次要功能：

• 命名空间：nerdctl --namespace=<NS> ps。 （注意：所有Kubernetes容器都在k8s.io containerd命名空间中，与Kubernetes命名空间无关）
• 导出Docker/OCI双格式归档：nerdctl save。
• 导入OCI归档以及Docker归档：nerdctl load。
• 指定非镜像rootfs：nerdctl run -it --rootfs <ROOTFS> /bin/sh。CLI语法符合Podman约定。
• 同时将容器连接到多个网络：nerdctl run --net foo --net bar
• 运行FreeBSD jail。
• 更好的多平台支持，例如，nerdctl pull --all-platforms IMAGE
• 将（现有的）AppArmor配置文件应用于无根容器：nerdctl run --security-opt apparmor=<PROFILE>。 使用sudo nerdctl apparmor load加载nerdctl-default配置文件。
• Systemd兼容性支持：nerdctl run --systemd=always

次要功能：

• 检查原始OCI配置：nerdctl container inspect --mode=native。

在nerdctl中先于Docker实现的功能

• 递归只读（RRO）绑定挂载：nerdctl run -v /mnt:/mnt:rro（使子目录如 /mnt/usb 也变为只读）。 需要内核版本 >= 5.12。 这个功能后来在 Docker v25 中以不同的语法引入。nerdctl 未来也将支持 Docker v25 的语法。

类似工具

• ctr：与 Docker CLI 不兼容，且不够用户友好。 值得注意的是，ctr 缺少以下 nerdctl 命令的等效功能：

  • nerdctl run -p <PORT>
  • nerdctl run --restart=always --net=bridge
  • 使用 ~/.docker/config.json 和凭证助手二进制文件（如 docker-credential-ecr-login）的 nerdctl pull
  • nerdctl logs
  • nerdctl build
  • nerdctl compose up

• crictl：与 Docker CLI 不兼容，不够用户友好，且不支持非 CRI 功能

• k3c v0.2（已废弃）：需要额外的守护进程，且不支持非 CRI 功能

• Rancher Kim（原 k3c v0.3）：需要 Kubernetes，仅专注于镜像管理命令，如 kim build 和 kim push

• PouchContainer（已废弃？）：需要额外的守护进程

开发者指南

nerdctl 是 containerd 的非核心子项目，采用 Apache 2.0 许可证。 作为 containerd 的非核心子项目，你可以在我们的 containerd/project 仓库中找到：

• 项目治理，
• 维护者，
• 以及贡献指南

等信息。

从源代码编译 nerdctl

运行 make && sudo make install。

查看 go.mod 头部以了解支持的最低 Go 版本。

虽然可以使用 go install github.com/containerd/nerdctl/v2/cmd/nerdctl，但不推荐，因为这种方式无法填充 nerdctl version 输出的版本信息。

测试

参见 测试 nerdctl。

为 nerdctl 做贡献

目前还有许多命令和标志尚未实现。非常欢迎提交拉取请求。

请确保您的开发者原创声明（DCO），通过使用 git commit -s 并使用您的真实姓名签署您的提交。

命令参考

已移至 ./docs/command-reference.md

附加文档

配置指南：

• ./docs/config.md：配置（/etc/nerdctl/nerdctl.toml，~/.config/nerdctl/nerdctl.toml）
• ./docs/registry.md：注册表认证（~/.docker/config.json）

基本功能：

• ./docs/compose.md：Compose
• ./docs/rootless.md：无根模式
• ./docs/cni.md：容器网络的 CNI
• ./docs/build.md：使用 BuildKit 的 nerdctl build

高级功能：

• ./docs/stargz.md：使用 Stargz Snapshotter 进行延迟拉取
• ./docs/nydus.md：使用 Nydus Snapshotter 进行延迟拉取
• ./docs/overlaybd.md：使用 OverlayBD Snapshotter 进行延迟拉取
• ./docs/ocicrypt.md：运行加密镜像
• ./docs/gpu.md：在容器内使用 GPU
• ./docs/multi-platform.md：多平台模式

实验性功能：

• ./docs/experimental.md：实验性功能
• ./docs/freebsd.md：运行 FreeBSD 监狱
• ./docs/ipfs.md：在 IPFS 上分发镜像
• ./docs/builder-debug.md：Dockerfile 的交互式调试

实现细节：

• ./docs/dir.md：目录布局（/var/lib/nerdctl）

其他：

• ./docs/faq.md：常见问题解答和故障排除