如何使用 Docker 设置 Ultralytics？

要使用 Docker 设置 Ultralytics，首先确保你的系统已安装 Docker。如果你有 NVIDIA GPU，请安装 NVIDIA Container Toolkit 以启用 GPU 支持。然后，使用以下命令从 Docker Hub 拉取最新的 Ultralytics Docker 镜像：. 有关详细步骤，请参阅我们的 Docker 快速入门指南。

在机器学习项目中使用 Ultralytics Docker 镜像有哪些好处？

使用 Ultralytics Docker 镜像可以确保不同计算机之间拥有一致的环境，复现相同的软件和依赖项。这对于跨团队协作、在各种硬件上运行模型以及保持可复现性尤其有用。一般 NVIDIA GPU 训练请使用 latest；对于 NVIDIA Jetson 设备，请选择与你的 JetPack 版本匹配的镜像。请参阅完整镜像表，或浏览 Ultralytics Docker Hub。

如何在支持 GPU 的 Docker 容器中运行 Ultralytics YOLO？

首先，确保已安装并配置 NVIDIA Container Toolkit。然后，使用以下命令运行支持 GPU 的 Ultralytics YOLO：. 此命令会设置一个可访问 GPU 的 Docker 容器。有关更多详细信息，请参阅 Docker 快速入门指南。

如何在带显示服务器的 Docker 容器中可视化 YOLO 预测结果？

要在 Docker 容器中通过 GUI 可视化 YOLO 预测结果，你需要允许 Docker 访问显示服务器。对于运行 X11 的系统，命令如下：. 对于运行 Wayland 的系统，请使用：. 更多信息请参阅在 Docker 容器中运行图形用户界面 (GUI) 应用程序部分。

我可以将本地目录挂载到 Ultralytics Docker 容器中吗？

可以，你可以使用 -v 标志将本地目录挂载到 Ultralytics Docker 容器中：. 将 /path/on/host 替换为本地计算机上的目录，并将 /path/in/container 替换为容器内的目标路径。这样，你就可以在容器中使用本地文件。有关更多信息，请参阅文件访问说明部分。

Ultralytics Docker 快速入门指南#

Ultralytics Docker Package Visual

本指南全面介绍如何为你的 Ultralytics 项目设置 Docker 环境。Docker 是一个用于在容器中开发、交付和运行应用程序的平台。它特别适合确保软件无论部署在哪里都能始终以相同方式运行。有关更多详细信息，请访问 Docker Hub 上的 Ultralytics Docker 仓库。

你将学到什么#

设置支持 NVIDIA 的 Docker
安装 Ultralytics Docker 镜像
在支持 CPU 或 GPU 的 Docker 容器中运行 Ultralytics
使用显示服务器和 Docker 显示 Ultralytics 检测结果
将本地目录挂载到容器中

Watch: How to Get started with Docker | Usage of Ultralytics Python Package inside Docker live demo 🎉

前置条件#

确保你的系统已安装 Docker。如果尚未安装，可以从 Docker 网站下载并安装。
如需 GPU 加速，请确保你的系统配备 NVIDIA GPU，并已安装 NVIDIA 驱动程序。CPU 镜像不需要 NVIDIA 硬件。
如果你使用 NVIDIA Jetson 设备，请确保已安装适当版本的 JetPack。有关更多详细信息，请参阅 NVIDIA Jetson 指南。

设置支持 NVIDIA 的 Docker（可选）#

首先，运行以下命令验证 NVIDIA 驱动程序是否已正确安装：

nvidia-smi

安装 NVIDIA Container Toolkit#

现在，让我们安装 NVIDIA Container Toolkit，以启用 Docker 容器中的 GPU 支持：

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
    | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

更新软件包列表并安装 NVIDIA Container Toolkit：

sudo apt-get update

sudo apt-get install -y nvidia-container-toolkit

使用 Docker 验证 CDI 设备#

运行 nvidia-ctk cdi list，确保 GPU CDI 设备可用（该工具包的 nvidia-cdi-refresh 服务会在 toolkit >= 1.18 时自动生成并维护规范）：

nvidia-ctk cdi list

你应该会看到类似 nvidia.com/gpu=0 和 nvidia.com/gpu=all 的条目。已发现的 CDI 设备也会显示在 docker info 中。

安装 Ultralytics Docker 镜像#

Ultralytics 将以下镜像发布到 Docker Hub。每个镜像都由 Docker 发布工作流根据其链接的 Dockerfile 构建。

标签	平台和用途	来源
`latest`	带 CUDA 的 Linux AMD64，用于 GPU 训练和推理	`Dockerfile`
`latest-export`	带 CUDA 和导出依赖项的 Linux AMD64，用于转换和基准测试	`Dockerfile-export`
`latest-python`	用于 CPU 推理的轻量级 Linux AMD64 Python 镜像	`Dockerfile-python`
`latest-python-export`	带导出依赖项的 Linux AMD64 CPU 镜像	`Dockerfile-python-export`
`latest-cpu`	以 Bash 作为默认命令的 Linux AMD64 CPU 镜像	`Dockerfile-cpu`
`latest-jupyter`	包含 JupyterLab 和 Ultralytics 教程 notebooks 的 Linux AMD64 CPU 镜像	`Dockerfile-jupyter`
`latest-arm64`	适用于 Apple silicon、Raspberry Pi 和其他 ARM64 系统的 Linux ARM64 CPU 镜像	`Dockerfile-arm64`
`latest-nvidia-arm64`	适用于 DGX Spark (DGX OS) 的 Linux ARM64 和适用于 Thor (JetPack 7.1) 的 PyTorch；捆绑的 TensorRT 不支持 JetPack	`Dockerfile-nvidia-arm64`
`latest-jetson-jetpack6`	适用于运行 JetPack 6 的 NVIDIA Jetson 设备的 Linux ARM64	`Dockerfile-jetson-jetpack6`
`latest-jetson-jetpack5`	适用于运行 JetPack 5 的 NVIDIA Jetson 设备的 Linux ARM64	`Dockerfile-jetson-jetpack5`
`latest-jetson-jetpack4`	适用于运行 JetPack 4 的 NVIDIA Jetson 设备的 Linux ARM64	`Dockerfile-jetson-jetpack4`
`latest-runner`	用于自托管 GitHub Actions GPU runner 的 Linux AMD64 CUDA 镜像	`Dockerfile-runner`
`latest-runner-cpu`	用于自托管 GitHub Actions CPU runner 的 Linux AMD64 镜像	`Dockerfile-runner-cpu`

AMD64 GPU 镜像（latest、latest-export 和 latest-runner）使用 PyTorch 2.14 和 CUDA 13.2。在启动 AMD64 GPU 镜像之前，请使用 nvidia-smi 检查宿主机驱动程序的 CUDA 支持情况；安装较新的容器不会升级宿主机驱动程序。CUDA 13 移除了对 Maxwell、Pascal 和 Volta GPU 的支持，包括 Tesla P100 和 V100。请参见 NVIDIA 的 CUDA 发行说明和驱动程序兼容性要求。

NVIDIA ARM64 镜像使用带有 CUDA 13.4 和 TensorRT 11.2 的 NVIDIA PyTorch 26.08。NVIDIA ARM64 镜像对 Thor 的 PyTorch 支持不扩展到 TensorRT：NVIDIA 不在 JetPack 上支持 TensorRT 11.2。对于 Jetson TensorRT 导出，请为你的 JetPack 版本使用受支持的 TensorRT 10.x 运行时。请遵循Jetson 指南或DGX Spark 指南中的平台要求。JetPack 4、5 和 6 镜像保留其各自独立的特定设备软件栈。

Conda Dockerfile 可用于本地构建；latest-conda 的自动发布已被禁用，因此该镜像仓库标签不包含这些更新。

请使用 latest-python-export 进行 LiteRT 导出。GPU latest-export 镜像保留了 PyTorch 2.14 并且省略了 LiteRT，因为 LiteRT 当前的依赖项要求 PyTorch 版本低于 2.14。

以 latest 开头的标签跟踪最新发布的主分支构建版本。带版本号的标签会将 latest 前缀替换为 Ultralytics 版本，例如 VERSION、VERSION-cpu 或 VERSION-jetson-jetpack6。如需可复现的环境，请使用带版本号的标签。

拉取最新镜像：

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latest

如果你想自行构建镜像，请克隆仓库，并传入上表中匹配的 Dockerfile，同时将仓库根目录用作构建上下文：

# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .

在 Docker 容器中运行 Ultralytics#

以下是运行 Ultralytics Docker 容器的方法：

仅使用 CPU#

# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpu

使用 GPU#

# Run with all GPUs
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --device nvidia.com/gpu=2 --device nvidia.com/gpu=3 ultralytics/ultralytics:latest

-it 标志会分配伪 TTY 并保持 stdin 打开，使你能够与容器交互。--ipc=host 标志启用与主机共享 IPC 命名空间，这对于在进程之间共享内存至关重要。--device nvidia.com/gpu=... 标志通过 CDI 授予容器访问主机 GPU 的权限。

使用 CDI 替代 `--gpus all`

在 Linux 上，CDI 设备请求需要 Docker >= 28.2.0（默认启用 CDI）和 nvidia-container-toolkit >= 1.18（自动生成 CDI 规范）。运行 GPU 容器前，请升级较旧的 Linux 主机。旧版 --gpus all 标志可能会在主机于例行软件包更新期间重新加载 systemd 时丢失 GPU 访问权限（Failed to initialize NVML: Unknown Error）（nvidia-container-toolkit#48）。CDI --device 请求会将设备节点包含在容器配置中，因此训练 worker 或 CI runner 等长时间运行的容器在重新加载后仍能保持 GPU 访问权限。

Windows 上的 Docker Desktop GPU 支持目前使用带 WSL 2 后端的 --gpus all，因为 NVIDIA CDI 设备在该环境中不可用。Windows 不使用 Linux systemd，因此上述 daemon-reload 故障不适用。

文件访问说明#

要在容器中使用本地计算机上的文件，你可以使用 Docker 卷：

# Mount a local directory into the container
sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

将 /path/on/host 替换为本地计算机上的目录路径，并将 /path/in/container 替换为 Docker 容器中的目标路径。

持久化训练输出#

默认情况下，训练输出会保存到容器内的 /ultralytics/runs/<task>/<name>/。如果不挂载主机目录，容器删除后输出将会丢失。

持久化训练输出：

# Recommended: mount workspace and specify project path
sudo docker run --rm -it -v "$(pwd)":/w -w /w ultralytics/ultralytics:latest \
  yolo train model=yolo26n.pt data=coco8.yaml project=/w/runs

这会将所有训练输出保存到主机上的 ./runs。

在 Docker 容器中运行图形用户界面 (GUI) 应用程序#

高度实验性 - 用户自行承担全部风险

以下说明具有实验性。与 Docker 容器共享 X11 套接字可能带来安全风险。因此，建议仅在受控环境中测试此解决方案。有关更多信息，请参阅这些关于如何使用 xhost⁽¹⁾⁽²⁾ 的资源。

Docker 主要用于将后台应用程序和 CLI 程序容器化，但也可以运行图形程序。在 Linux 世界中，有两种主要的图形服务器负责处理图形显示：X11（也称为 X Window System）和 Wayland。开始之前，必须确定你当前使用的是哪种图形服务器。运行以下命令进行查看：

env | grep -E -i 'x11|xorg|wayland'

X11 或 Wayland 显示服务器的设置和配置不在本指南的范围内。如果上述命令没有返回任何内容，你需要先在系统中启用其中一种显示服务器，然后再继续。

使用 GUI 运行 Docker 容器#

示例

使用 GPU

如果你使用 GPU，可以将 --device nvidia.com/gpu=all 标志添加到命令中。

如果你使用 X11，可以运行以下命令，使 Docker 容器能够访问 X11 套接字：

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v ~/.Xauthority:/root/.Xauthority \
  -it --ipc=host ultralytics/ultralytics:latest

此命令会将 DISPLAY 环境变量设置为主机的显示器，挂载 X11 套接字，并将 .Xauthority 文件映射到容器中。xhost +local:docker 命令允许 Docker 容器访问 X11 服务器。

使用带 GUI 的 Docker#

现在，你可以在 Docker 容器中显示图形应用程序。例如，你可以运行以下 CLI 命令，以可视化 YOLO26 模型的预测结果：

yolo predict model=yolo26n.pt show=True

测试

验证 Docker 组是否有权访问 X11 服务器的一种简单方法，是运行带有 xclock 或 xeyes 等 GUI 程序的容器。或者，你也可以在 Ultralytics Docker 容器中安装这些程序，以测试其对 GNU-Linux 显示服务器 X11 的访问权限。如果遇到问题，可以考虑设置环境变量 -e QT_DEBUG_PLUGINS=1。设置此环境变量会启用调试信息输出，有助于排查问题。

完成 Docker GUI 操作后#

撤销访问权限

无论采用哪种方式，完成后都不要忘记撤销 Docker 组的访问权限。

xhost -local:docker

想直接在终端中查看图像结果？

请参阅以下指南：使用终端查看图像结果

现在，你已经完成了使用 Ultralytics 和 Docker 的设置，可以开始利用其功能。如需自托管 Ultralytics Web 应用程序，请参阅 Platform 本地部署指南。如需了解其他 Python 软件包安装方法，请参阅 Ultralytics 快速入门文档。

常见问题#

要使用 Docker 设置 Ultralytics，首先确保你的系统已安装 Docker。如果你有 NVIDIA GPU，请安装 NVIDIA Container Toolkit 以启用 GPU 支持。然后，使用以下命令从 Docker Hub 拉取最新的 Ultralytics Docker 镜像：
sudo docker pull ultralytics/ultralytics:latest
有关详细步骤，请参阅我们的 Docker 快速入门指南。
使用 Ultralytics Docker 镜像可以确保不同计算机之间拥有一致的环境，复现相同的软件和依赖项。这对于跨团队协作、在各种硬件上运行模型以及保持可复现性尤其有用。一般 NVIDIA GPU 训练请使用 latest；对于 NVIDIA Jetson 设备，请选择与你的 JetPack 版本匹配的镜像。请参阅完整镜像表，或浏览 Ultralytics Docker Hub。
首先，确保已安装并配置 NVIDIA Container Toolkit。然后，使用以下命令运行支持 GPU 的 Ultralytics YOLO：
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUs
此命令会设置一个可访问 GPU 的 Docker 容器。有关更多详细信息，请参阅 Docker 快速入门指南。
要在 Docker 容器中通过 GUI 可视化 YOLO 预测结果，你需要允许 Docker 访问显示服务器。对于运行 X11 的系统，命令如下：
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v ~/.Xauthority:/root/.Xauthority \ -it --ipc=host ultralytics/ultralytics:latest
对于运行 Wayland 的系统，请使用：
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \ --net=host -it --ipc=host ultralytics/ultralytics:latest
更多信息请参阅在 Docker 容器中运行图形用户界面 (GUI) 应用程序部分。
可以，你可以使用 -v 标志将本地目录挂载到 Ultralytics Docker 容器中：
sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest
将 /path/on/host 替换为本地计算机上的目录，并将 /path/in/container 替换为容器内的目标路径。这样，你就可以在容器中使用本地文件。有关更多信息，请参阅文件访问说明部分。

贡献者

GLglenn-jocher²⁰ RAraimbekovm³ ONonuralpszr³ RIRizwanMunawar² AMambitious-octopus¹ PDpderrenger¹ SHSHOscarChen¹ PIpicsalex¹ LAlakshanthad¹ FRFruchtzwerg94¹ BUBurhan-Q¹ JPJpfonseca¹

创建时间 2023年11月12日更新时间上周