Ultralytics Docker 快速入门指南#
本指南全面介绍了如何为你的 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 updatesudo apt-get install -y nvidia-container-toolkit使用 Docker 验证 CDI 设备#
运行 nvidia-ctk cdi list 以确保 GPU CDI 设备可用（toolkit 版本 >= 1.18 时，该工具包的 nvidia-cdi-refresh 服务会自动生成并维护规范）：
nvidia-ctk cdi list你应该能看到诸如 nvidia.com/gpu=0 和 nvidia.com/gpu=all 的条目。发现的 CDI 设备也会显示在 docker info 中。
安装 Ultralytics Docker 镜像#
Ultralytics 在 Docker Hub 上发布了以下镜像。每个镜像均由Docker 发布工作流根据其关联的 Dockerfile 构建而成。
以 latest 开头的标签会跟踪最近发布的 main 分支构建。带版本的标签则将 latest 前缀替换为 Ultralytics 的版本号，例如 VERSION、VERSION-cpu 或 VERSION-jetson-jetpack6。若要获得可重复的环境，请使用带版本的标签。
拉取最新镜像：
# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latest在 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 的权限。
在 Linux 上，CDI 设备请求需要 Docker >= 28.2.0（默认启用 CDI）以及 nvidia-container-toolkit >= 1.18（自动生成 CDI 规范）。在运行 GPU 容器之前，请升级较旧的 Linux 主机。在常规软件包更新期间，当主机重新加载 systemd 时，旧版的 --gpus all 标志可能会丢失 GPU 访问权限（Failed to initialize NVML: Unknown Error）（nvidia-container-toolkit#48）。CDI --device 请求将设备节点包含在容器配置中，因此诸如训练工作线程或 CI 运行程序等长时间运行的容器在重新加载后仍可保留 GPU 访问权限。
Windows 上的 Docker Desktop GPU 支持目前将带有 WSL 2 后端的 --gpus all 结合使用，因为 NVIDIA CDI 设备在那里不可用。Windows 不使用 Linux systemd，因此上述守护进程重新加载失败的情况不适用。
关于文件访问权限的说明#
若要在容器内处理本地计算机上的文件，可以使用 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 主要用于容器化后台应用程序和 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 服务器。
将 Docker 与 GUI 结合使用#
现在你可以在 Docker 容器内显示图形应用程序。例如，你可以运行以下 CLI 命令来可视化 YOLO26 模型的预测结果：
yolo predict model=yolo26n.pt show=True测试
结束使用 Docker GUI 后#
无论哪种情况，完成后都别忘了从 Docker 组撤销访问权限。
xhost -local:docker想直接在终端中查看图像结果吗？
请参考以下关于使用终端查看图像结果的指南
你现在已准备好将 Ultralytics 与 Docker 配合使用，并准备充分利用其各项功能。若要自托管 Ultralytics Web 应用程序，请参见平台本地部署指南。有关其他 Python 软件包安装方法，请参见 Ultralytics 快速入门文档。
常见问题解答#
如何设置 Ultralytics Docker？#
要将 Ultralytics 与 Docker 配合使用，请首先确保系统上已安装 Docker。如果你拥有 NVIDIA GPU，请安装 NVIDIA Container Toolkit 以启用 GPU 支持。然后，使用以下命令从 Docker Hub 拉取最新的 Ultralytics Docker 镜像：
sudo docker pull ultralytics/ultralytics:latest详细步骤请参考我们的 Docker 快速入门指南。
为机器学习项目使用 Ultralytics Docker 镜像有哪些好处？#
使用 Ultralytics Docker 镜像可确保不同机器之间的环境一致性，并复制相同的软件和依赖项。这对于跨团队协作、在各种硬件上运行模型以及保持可重复性特别有用。使用 latest 进行常规 NVIDIA GPU 训练，或者选择与你的 JetPack 版本匹配的镜像用于 NVIDIA Jetson 设备。请查看完整的镜像表格或探索 Ultralytics Docker Hub。
如何在具有 GPU 支持的 Docker 容器中运行 Ultralytics YOLO？#
首先，确保已安装并配置好 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 容器中可视化 YOLO 预测结果？#
要在 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) 应用程序部分找到。
我可以将本地目录挂载到 Ultralytics Docker 容器中吗？#
是的，你可以使用 -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 替换为容器内的目标路径。通过此设置，你可以在容器内使用本地文件。有关更多信息，请参考文件访问权限注意事项部分。