Ultralytics YOLO27：
Get Started

Ultralytics Docker 快速入门指南#

Ultralytics Docker Package Visual

本指南全面介绍如何为 Ultralytics 项目设置 Docker 环境。Docker 是一个用于开发、交付和运行容器化应用的平台。它特别适用于确保软件无论部署在何处都能以相同方式运行。更多详情请访问 Docker Hub 上的 Ultralytics Docker 仓库。

Docker 镜像版本 Docker 拉取次数

你将学到什么#

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


观看： 如何开始使用 Docker | 在 Docker 中使用 Ultralytics Python Package 的实时演示 🎉

前置条件#

  • 确保你的系统已安装 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 设备可用（在 toolkit >= 1.18 时，toolkit 的 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 构建。

标签平台和用途数据源
latestLinux AMD64，支持 CUDA，用于 GPU 训练和推理Dockerfile
latest-exportLinux AMD64，支持 CUDA 并包含导出依赖项，用于模型转换和基准测试Dockerfile-export
latest-amdLinux AMD64，支持 ROCm 和 MIGraphX，用于 AMD GPU 训练和推理Dockerfile-amd
latest-python适用于 CPU 推理的轻量级 Linux AMD64 Python 3.14 镜像Dockerfile-python
latest-python-export包含导出依赖项的 Linux AMD64 Python 3.13 CPU 镜像Dockerfile-python-export
latest-cpuLinux AMD64 CPU 镜像，默认命令为 BashDockerfile-cpu
latest-jupyterLinux AMD64 CPU 镜像，包含 JupyterLab 和 Ultralytics 教程笔记本Dockerfile-jupyter
latest-arm64适用于 Apple 芯片、Raspberry Pi 和其他 ARM64 系统的 Linux ARM64 Python 3.13 CPU 镜像Dockerfile-arm64
latest-nvidia-arm64适用于 DGX Spark（DGX OS）以及 Thor 上的 PyTorch（JetPack 7.1）的 Linux ARM64；随附的 TensorRT 不支持 JetPackDockerfile-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 运行器的 Linux AMD64 CUDA 镜像Dockerfile-runner
latest-runner-cpu用于自托管 GitHub Actions CPU 运行器的 Linux AMD64 镜像Dockerfile-runner-cpu

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

NVIDIA ARM64 镜像使用 NVIDIA PyTorch 26.08、CUDA 13.4 和 TensorRT 11.2。其 PyTorch 对 Thor 的支持不包括 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。

Python、CPU、Jupyter 和 CPU runner 镜像使用 Python 3.14。Python 导出镜像使用 latest-python-3.13 基础镜像，该镜像由相同的 Dockerfile-python 和 --build-arg PYTHON_VERSION=3.13 构建，因为 TensorFlow、CoreML 和 PaddlePaddle 目前尚不支持 Python 3.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 并保持标准输入打开，从而允许你与容器交互。--ipc=host 标志会启用对主机 IPC 命名空间的共享，这对进程间共享内存至关重要。对于 NVIDIA GPU，--device nvidia.com/gpu=... 标志会通过 CDI 授予访问权限。对于 AMD GPU，--device 标志会授予对 GPU 内核驱动程序（/dev/kfd）和显示渲染节点（/dev/dri）的访问权限。

使用 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 请求会将设备节点包含在容器配置中，因此训练工作进程或 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 容器共享 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，可以在命令中添加 --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#

Ultralytics 镜像预装无头版 OpenCV，因此请先在容器内安装 OpenCV 的 GUI 版本及其系统库：

apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 libsm6
pip uninstall -y opencv-python-headless && pip install opencv-python

现在，你可以在 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
想直接在终端中查看图像结果吗？

请参阅以下指南，了解如何使用终端查看图像结果。

现在，你已完成设置，可以使用 Docker 运行 Ultralytics，尽情发挥它的功能。如需自行托管 Ultralytics Web 应用，请参阅 Platform On-Premise 指南。如需了解其他 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

    在容器内，使用 show=True 之前，请先安装 OpenCV 的 GUI 版本，具体说明请参阅在 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-jocher22RAraimbekovm3ONonuralpszr3RIRizwanMunawar2IVIvan Tikhonov1AMambitious-octopus1PDpderrenger1SHSHOscarChen1PIpicsalex1LAlakshanthad1FRFruchtzwerg941BUBurhan-Q1JPJpfonseca1

评论