在 GitHub 上编辑页面 (EN)

Ultralytics Docker 快速入门指南

Ultralytics Docker Package Visual

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

Docker Image Version Docker Pulls

你将学到什么

  • 配置带 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 官网 下载并安装它。
  • 确保你的系统配备 NVIDIA GPU 并安装了 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

安装最新版本的 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

验证 Docker 的 NVIDIA 运行时

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

docker info | grep -i runtime

安装 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

在 Docker 容器中运行 Ultralytics

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

仅使用 CPU

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

使用 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。

关于文件可访问性的说明

要处理容器内本地机器上的文件，你可以使用 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 容器内所需的路径。

持久化训练输出

默认情况下，训练输出会保存到容器内的 /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 的更多信息，请参考这些资源(1)(2)。

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

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

X11 或 Wayland 显示服务器的安装和配置超出了本指南的范围。如果上述命令没有返回结果，那么在继续之前，你需要先让其中一个在你的系统中正常工作。

运行带 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 服务器。

在 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。设置此环境变量可以启用调试信息的输出，从而辅助排查过程。

当完成 Docker GUI 操作后

撤销访问权限

在这两种情况下，完成工作后别忘了撤销 Docker 组的访问权限。

xhost -local:docker
想直接在终端中查看图像结果吗？

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

你现在已经完成了 Ultralytics 与 Docker 的配置，准备好充分利用其各项功能了。有关其他安装方法，请参阅 Ultralytics 快速入门文档。

常见问题 (FAQ)

如何使用 Docker 设置 Ultralytics？

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

sudo docker pull ultralytics/ultralytics:latest

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

将 Ultralytics Docker 镜像用于机器学习项目有哪些好处？

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

如何在一个支持 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 快速入门指南。

如何可视化 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 --runtime=nvidia --gpus all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

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

Contributors
在 GitHub 上编辑页面 (EN)
GLglenn-jocher14ONonuralpszr3RIRizwanMunawar2RAraimbekovm1PDpderrenger1SHSHOscarChen1PIpicsalex1LAlakshanthad1FRFruchtzwerg941BUBurhan-Q1JOJoão Fonseca1

评论