Link to this sectionUltralytics Docker 快速入门指南#

Ultralytics Docker Package Visual

本指南旨在为你介绍如何为 Ultralytics 项目配置 Docker 环境。Docker 是一个用于在容器中开发、发布和运行应用程序的平台。它对于确保软件无论部署在何处都能保持运行一致性非常有帮助。更多详细信息，请访问 Docker Hub 上的 Ultralytics Docker 仓库。

Link to this section你将学到什么#

配置具有 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 🎉

Link to this section前提条件#

确保你的系统已安装 Docker。如果没有，你可以从 Docker 官网下载并安装。
确保你的系统配有 NVIDIA GPU 并且已安装 NVIDIA 驱动程序。
如果你正在使用 NVIDIA Jetson 设备，请确保已安装相应的 JetPack 版本。有关更多详细信息，请参阅 NVIDIA Jetson 指南。

Link to this section配置具有 NVIDIA 支持的 Docker#

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

nvidia-smi

Link to this section安装 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

安装最新版本的 nvidia-container-toolkit：

sudo apt-get install -y nvidia-container-toolkit \
  nvidia-container-toolkit-base libnvidia-container-tools \
  libnvidia-container1

可选：安装特定版本的 nvidia-container-toolkit

你可以选择通过设置 NVIDIA_CONTAINER_TOOLKIT_VERSION 环境变量来安装特定版本的 nvidia-container-toolkit：

export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.17.8-1
sudo apt-get install -y \
  nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Link to this section验证 Docker 的 NVIDIA 运行时#

运行 docker info | grep -i runtime 以确保 nvidia 出现在运行时列表中：

docker info | grep -i runtime

Link to this section安装 Ultralytics Docker 镜像#

Ultralytics 提供多种针对不同平台和应用场景优化的 Docker 镜像：

Dockerfile: GPU 镜像，非常适合进行训练。
Dockerfile-arm64: 针对 ARM64 架构，适用于 Raspberry Pi 等设备。
Dockerfile-cpu: 仅限 CPU 的版本，用于推理和非 GPU 环境。
Dockerfile-jetson-jetpack4: Optimized for NVIDIA Jetson devices running NVIDIA JetPack 4.
Dockerfile-jetson-jetpack5: Optimized for NVIDIA Jetson devices running NVIDIA JetPack 5.
Dockerfile-jetson-jetpack6: Optimized for NVIDIA Jetson devices running NVIDIA JetPack 6.
Dockerfile-jupyter: 用于在浏览器中使用 JupyterLab 进行交互式开发。
Dockerfile-nvidia-arm64: 针对 Jetson AGX Thor 和 DGX Spark 等 NVIDIA ARM64 设备，支持 JetPack 7.0 和 DGX OS。
Dockerfile-python: 极简 Python 环境，适用于轻量级应用。
Dockerfile-python-export: 极简 Python 镜像，扩展了完整的导出功能，用于 YOLO 模型转换。
Dockerfile-conda: 包含 Miniconda3 并通过 Conda 安装了 Ultralytics 包。
Dockerfile-export: GPU 镜像，预装了所有用于模型转换和基准测试的导出格式依赖项。

拉取最新镜像：

# Set image name as a variable
t=ultralytics/ultralytics:latest

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull $t

Link to this section在 Docker 容器中运行 Ultralytics#

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

Link to this section仅使用 CPU#

# Run without GPU
sudo docker run -it --ipc=host $t

Link to this section使用 GPU#

# Run with all GPUs
sudo docker run -it --ipc=host --runtime=nvidia --gpus all $t

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --runtime=nvidia --gpus '"device=2,3"' $t

-it 标志分配一个伪终端并保持 stdin 打开，使你可以与容器交互。--ipc=host 标志用于启用主机 IPC 命名空间的共享，这对于进程间共享内存至关重要。--gpus 标志允许容器访问主机的 GPU。

Link to this section关于文件访问权限的说明#

若要在容器内处理本地计算机上的文件，可以使用 Docker 数据卷：

# Mount a local directory into the container
sudo docker run -it --ipc=host --runtime=nvidia --gpus all -v /path/on/host:/path/in/container $t

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

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

高度实验性 - 用户自行承担所有风险

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

Docker 主要用于容器化后台应用程序和 CLI 程序，但它也可以运行图形化程序。在 Linux 环境中，有两个主要的图形服务器处理图形显示：X11（也称为 X Window System）和 Wayland。在开始之前，确认你当前使用的图形服务器至关重要。运行此命令进行查看：

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

X11 或 Wayland 显示服务器的安装和配置不在本指南范围内。如果上述命令未返回任何内容，则在继续之前，你需要先让其中一个服务器在你的系统上运行起来。

Link to this section运行带 GUI 的 Docker 容器#

示例

使用 GPU

如果你正在使用 GPU，可以在命令中添加 --gpus all 标志。

Docker 运行时标志

如果你的 Docker 安装默认不使用 nvidia 运行时，可以在命令中添加 --runtime=nvidia 标志。

如果你使用的是 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 $t

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

Link to this section将 Docker 与 GUI 结合使用#

Now you can display graphical applications inside your Docker container. For example, you can run the following CLI command to visualize the predictions from a YOLO26 model:

yolo predict model=yolo26n.pt show=True

测试

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

Link to this section结束使用 Docker GUI 后#

撤销访问权限

无论哪种情况，完成后都别忘了从 Docker 组撤销访问权限。

xhost -local:docker

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

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

你现在已经完成了使用 Docker 配置 Ultralytics 的设置，并准备好发挥它的功能了。如需其他安装方法，请参阅 Ultralytics 快速入门文档。

Link to this section常见问题解答#

Link to this section如何设置 Ultralytics Docker？#

要设置 Ultralytics Docker，请先确保你的系统已安装 Docker。如果你有 NVIDIA GPU，请安装 NVIDIA Container Toolkit 以启用 GPU 支持。然后，使用以下命令从 Docker Hub 拉取最新的 Ultralytics Docker 镜像：

sudo docker pull ultralytics/ultralytics:latest

详细步骤请参考我们的 Docker 快速入门指南。

Link to this section为机器学习项目使用 Ultralytics Docker 镜像有哪些好处？#

使用 Ultralytics Docker 镜像可确保不同机器之间的环境一致性，从而复制相同的软件和依赖项。这对于跨团队协作、在各种硬件上运行模型以及保持可重复性特别有用。对于基于 GPU 的训练，Ultralytics 提供了优化的 Docker 镜像，例如用于通用 GPU 用途的 Dockerfile 和用于 NVIDIA Jetson 设备的 Dockerfile-jetson。更多详细信息，请浏览 Ultralytics Docker Hub。

Link to this section如何在具有 GPU 支持的 Docker 容器中运行 Ultralytics YOLO？#

首先，确保已安装并配置好 NVIDIA Container Toolkit。然后，使用以下命令运行具有 GPU 支持的 Ultralytics YOLO：

sudo docker run -it --ipc=host --runtime=nvidia --gpus all ultralytics/ultralytics:latest # all GPUs

该命令将创建一个具有 GPU 访问权限的 Docker 容器。更多详细信息，请参阅 Docker 快速入门指南。

Link to this section如何在使用显示服务器的 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) 应用程序一节中找到。

Link to this section我可以将本地目录挂载到 Ultralytics Docker 容器中吗？#

是的，你可以使用 -v 标志将本地目录挂载到 Ultralytics Docker 容器中：

sudo docker run -it --ipc=host --runtime=nvidia --gpus all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

将 /path/on/host 替换为本地计算机上的目录，将 /path/in/container 替换为容器内的目标路径。此设置允许你在容器内处理本地文件。有关更多信息，请参考关于文件访问权限的说明一节。

贡献者

GLglenn-jocher¹⁵ ONonuralpszr³ RIRizwanMunawar² RAraimbekovm¹ PDpderrenger¹ SHSHOscarChen¹ PIpicsalex¹ LAlakshanthad¹ FRFruchtzwerg94¹ BUBurhan-Q¹JOJoão Fonseca¹

创建于 2023年11月12日更新于 3天前