Начать

Краткое руководство по Docker для Ultralytics

Ultralytics Docker images on Docker Hub

В этом руководстве показано, как настроить среду Docker для проектов Ultralytics. Docker — это платформа для разработки, доставки и запуска приложений в контейнерах, благодаря чему программное обеспечение работает одинаково независимо от места развёртывания.

Версия Docker-образа Загрузки Docker-образа

Что ты узнаешь#

  • Настройка Docker с поддержкой NVIDIA
  • Установка Docker-образов Ultralytics
  • Запуск Ultralytics в контейнере Docker с поддержкой CPU или GPU
  • Использование сервера дисплея с Docker для отображения результатов детекции Ultralytics
  • Подключение локальных каталогов к контейнеру


Смотри: Как начать работу с Docker | Демонстрация работы пакета Ultralytics Python в Docker 🎉

Предварительные требования#

  • Убедись, что Docker установлен в твоей системе. Если нет, скачай и установи его с сайта Docker.
  • Для ускорения на GPU убедись, что в системе установлены GPU NVIDIA и драйверы NVIDIA. Для образов CPU оборудование NVIDIA не требуется.
  • Если ты используешь устройства NVIDIA Jetson, убедись, что установлена подходящая версия JetPack. Подробнее см. в руководстве по NVIDIA Jetson.

Настройка Docker с поддержкой NVIDIA (необязательно)#

Сначала проверь правильность установки драйверов NVIDIA, выполнив команду:

nvidia-smi

Установка NVIDIA Container Toolkit#

Установи NVIDIA Container Toolkit, чтобы включить поддержку GPU в контейнерах Docker:

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

Проверка устройств CDI с помощью Docker#

Выполни 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.

Установка Docker-образов Ultralytics#

Ultralytics публикует следующие образы на Docker Hub. Каждый образ собирается из соответствующего Dockerfile с помощью процесса публикации Docker.

ТегПлатформа и назначениеИсточник
latestLinux AMD64 с CUDA для обучения и инференса на GPUDockerfile
latest-exportLinux AMD64 с CUDA и зависимостями для экспорта, конвертации и тестирования производительностиDockerfile-export
latest-amdLinux AMD64 с ROCm и MIGraphX для обучения и инференса на GPU AMDDockerfile-amd
latest-pythonОблегчённый образ Linux AMD64 с Python 3.14 для инференса на CPUDockerfile-python
latest-python-exportОбраз Linux AMD64 с Python 3.13 и CPU, включающий зависимости для экспортаDockerfile-python-export
latest-cpuОбраз Linux AMD64 для CPU, в котором Bash используется по умолчаниюDockerfile-cpu
latest-jupyterОбраз Linux AMD64 для CPU с JupyterLab и обучающими блокнотами UltralyticsDockerfile-jupyter
latest-arm64Образ Linux ARM64 с Python 3.13 и CPU для Apple silicon, Raspberry Pi и других систем ARM64Dockerfile-arm64
latest-nvidia-arm64Linux ARM64 для DGX Spark (DGX OS) и PyTorch на Thor (JetPack 7.1); встроенный TensorRT не поддерживает JetPackDockerfile-nvidia-arm64
latest-jetson-jetpack6Linux ARM64 для устройств NVIDIA Jetson под управлением JetPack 6Dockerfile-jetson-jetpack6
latest-jetson-jetpack5Linux ARM64 для устройств NVIDIA Jetson под управлением JetPack 5Dockerfile-jetson-jetpack5
latest-jetson-jetpack4Linux ARM64 для устройств NVIDIA Jetson под управлением JetPack 4Dockerfile-jetson-jetpack4
latest-runnerОбраз Linux AMD64 с CUDA для собственного раннера GitHub Actions с GPUDockerfile-runner
latest-runner-cpuОбраз Linux AMD64 для собственного раннера GitHub Actions с CPUDockerfile-runner-cpu

Образы GPU для AMD64 (latest, latest-export и latest-runner) используют PyTorch 2.15 и CUDA 13.2. Перед запуском проверь поддержку CUDA драйвером хоста с помощью nvidia-smi; установка более нового контейнера не обновляет драйвер хоста. В CUDA 13 прекращена поддержка GPU архитектур Maxwell, Pascal и Volta, включая Tesla P100 и V100.

В образе NVIDIA ARM64 используются NVIDIA PyTorch 26.10, CUDA 13.4 и TensorRT 11.4. Поддержка Thor в PyTorch не распространяется на TensorRT: NVIDIA не поддерживает TensorRT 11.4 в JetPack. Для экспорта TensorRT на Jetson используй поддерживаемую среду выполнения TensorRT 10.x для своей версии JetPack. Следуй требованиям платформы из руководства по Jetson или руководства по DGX Spark. В образах для JetPack 4, 5 и 6 используются отдельные стеки, предназначенные для соответствующих устройств.

Dockerfile для Conda доступен для локальной сборки; автоматическая публикация latest-conda отключена, поэтому этот тег в реестре не содержит этих обновлений.

В образах Python, CPU, Jupyter и CPU runner используется Python 3.14. В образе Python export используется базовый образ 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 .

Запуск Ultralytics в контейнере Docker#

Вот как запустить контейнер 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 выделяет псевдотерминал и оставляет stdin открытым, позволяя взаимодействовать с контейнером. Флаг --ipc=host включает совместное использование пространства имён IPC хоста, что необходимо для обмена памятью между процессами. Для GPU NVIDIA флаг --device nvidia.com/gpu=... предоставляет доступ через CDI. Для GPU AMD флаги --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 может привести к потере доступа к GPU (Failed to initialize NVML: Unknown Error), если хост перезагрузит systemd во время обычного обновления пакетов (nvidia-container-toolkit#48). Запросы CDI --device включают узлы устройств в конфигурацию контейнера, поэтому долго работающие контейнеры, например процессы обучения или раннеры CI, сохраняют доступ к GPU после перезагрузки.

Поддержка GPU в Docker Desktop на Windows сейчас использует --gpus all с серверной частью WSL 2, поскольку устройства 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 на хост-компьютере.

Запуск графических интерфейсов пользователя (GUI) в контейнере Docker#

Крайне экспериментально — пользователь принимает на себя все риски

Следующие инструкции носят экспериментальный характер. Подключение сокета X11 к контейнеру Docker сопряжено с потенциальными рисками безопасности. Поэтому это решение рекомендуется тестировать только в контролируемой среде.

Docker в основном используют для контейнеризации фоновых приложений и программ CLI, но он также может запускать графические программы. В Linux для отображения графики используются два основных графических сервера: X11 (также известная как оконная система X) и Wayland. Перед началом важно определить, какой графический сервер используется в данный момент. Выполни эту команду, чтобы узнать:

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

Настройка и конфигурирование сервера отображения X11 или Wayland не входят в задачи этого руководства. Если приведённая выше команда ничего не выводит, сначала нужно запустить любой из этих серверов в своей системе, а уже затем продолжить.

Запуск контейнера 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 с графическим интерфейсом#

В образах Ultralytics поставляется OpenCV без графического интерфейса, поэтому сначала установи в контейнере сборку OpenCV с графическим интерфейсом и системные библиотеки:

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. Также можно установить эти программы в контейнер Ultralytics Docker, чтобы проверить доступ к серверу X11 графического сервера GNU/Linux. Если возникнут проблемы, попробуй задать переменную окружения -e QT_DEBUG_PLUGINS=1. Ее установка включает вывод отладочной информации, которая поможет найти и устранить неполадки.

После завершения работы с графическим интерфейсом Docker#

Отзыв доступа

В обоих случаях не забудь отозвать доступ группы Docker, когда закончишь.

xhost -local:docker
Хочешь просматривать результаты обработки изображений прямо в терминале?

Теперь ты можешь использовать Ultralytics с Docker. Чтобы разместить веб-приложение Ultralytics на собственном сервере, смотри руководство по локальному развёртыванию платформы.

Часто задаваемые вопросы#

  • Чтобы настроить Ultralytics с Docker, сначала убедись, что Docker установлен в системе. Если у тебя есть GPU NVIDIA, установи NVIDIA Container Toolkit, чтобы включить поддержку GPU. Затем загрузи последнюю версию образа Ultralytics Docker из Docker Hub с помощью следующей команды:

    sudo docker pull ultralytics/ultralytics:latest
  • Использование образов Ultralytics Docker обеспечивает одинаковую среду на разных машинах, включая идентичное программное обеспечение и зависимости. Это особенно полезно для совместной работы команд, запуска моделей на разном оборудовании и воспроизводимого развёртывания моделей. Используй latest для обычного обучения на GPU NVIDIA или выбери образ, соответствующий версии JetPack для устройства NVIDIA Jetson.

  • Сначала убедись, что NVIDIA Container Toolkit установлен и настроен. Затем выполни следующую команду, чтобы запустить Ultralytics YOLO с поддержкой GPU:

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

    Эта команда создает контейнер Docker с доступом к GPU. Доступ можно ограничить выбранными GPU или переключить на AMD ROCm.

  • Чтобы визуализировать результаты предсказаний YOLO с графическим интерфейсом в контейнере Docker, нужно разрешить 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

    В контейнере установи сборку OpenCV с графическим интерфейсом перед использованием show=True, как описано в разделе Запуск приложений с графическим пользовательским интерфейсом (GUI) в контейнере Docker.

  • Да, локальные каталоги можно подключить к контейнеру Docker Ultralytics с помощью флага -v:

    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 — на нужный путь внутри контейнера. Такая настройка позволяет работать с локальными файлами из контейнера. Дополнительную информацию см. в разделе «Примечание о доступе к файлам».

Комментарии14

Задай вопрос, поделись результатами или помоги кому-нибудь.

  1. Letícia Rama

    Hello,

    Is this workflow suitable for other YOLO families, such as YOLO26?

    1. Glenn JocherUltralytics

      Yes, the same workflow supports YOLO26 and other model families available in the ultralytics package—use an up-to-date official image and specify the appropriate weights, such as model=yolo26n.pt. See the Docker Quickstart Guide for current image options, and feel free to drop any follow-up questions here so the Ultralytics team can help.

      1
  2. HellaPinotGitHub

    Hello! I have been testing running yolov8 inside a container, things seem to work well however after a somewhat random amount of time the inference hangs with no error output.

    I know the container hasn't crashed as I am reading events from a processing queue and I can see new partitions are being allocated on another thread.

    I'm running two models one after the other (different sizes and detection classes), so I'm wondering if this could be the root of the issue? At no point would they be running at the same time.

    I believe it is happening exactly when I call predict. Its hard to debug as again it happens very randomly and there is not output from the container, it seems like there might be an infinite loop somewhere thats stopping it from continuing.

    Curious if anything like this has been encountered before?

    1. Glenn JocherUltralytics

      Hello! 👋

      It sounds like a tricky issue, especially since it occurs randomly. Here are a few suggestions that might help you isolate or resolve the problem:

      1. Logging and Monitoring: Enhance the logging within your container. Consider logging the input sizes and other relevant data before the prediction call, and make sure you're logging any exceptions that could be silently caught.

      2. Resource Checks: Ensure that there are no resource starvation issues, such as GPU memory not being freed up properly. Tools like nvidia-smi can help monitor GPU usage.

      3. Sequential Model Loading: Although the models are run sequentially and not in parallel, it could be beneficial to explicitly clear the memory after each model's predictions are done. This can be done by deleting model objects and calling torch.cuda.empty_cache() if you are using PyTorch.

      4. Hardware Testing: Run your container pointing the inference to CPU only for a time to see if the problem persists. This could help determine if the issue is related to GPU computation or not.

      5. Reproducibility Tactic: Since the issue is sporadic, try to determine if there’s a specific type of input or specific conditions under which this occurs more frequently.

      If these suggestions don't help, please provide more details or code snippets, and I’d be happy to dive deeper into this!

      Let me know how it goes!

  3. HWKevinhwkGitHub

    I want to install ultralytics using docker on top of NVIDIA TX2, is there a detailed procedure? The reason for this question is that after entering the command nvidia-smi in the TX2 terminal, the output is command not found, and I'm worried that the steps in the document above are not applicable to TX2.

    1. Paula DerrengerUltralytics(изменено)

      @HWKevinhwk hey there! 🚀 Setting up Ultralytics on NVIDIA TX2 with Docker can be a bit tricky if nvidia-smi is missing, but no worries.

      For NVIDIA Jetson platforms like TX2, nvidia-smi is typically not available, and you'll use tegrastats instead to monitor the GPU. The Jetson TX2 is supported on JetPack 4, so install JetPack 4 first, as it includes the NVIDIA drivers and libraries needed for GPU acceleration. Jetson devices use the Docker integration provided through JetPack with --runtime=nvidia rather than --gpus all. Then pull and run the Ultralytics Docker image for JetPack 4:

      t=ultralytics/ultralytics:latest-jetson-jetpack4
      sudo docker pull $t && sudo docker run -it --ipc=host --runtime=nvidia $t

      See the NVIDIA Jetson guide for details. If you encounter any specific issues, feel free to drop them here. Happy detecting! 🎉

    2. HWKevinhwkGitHub

      Is there a detailed tutorial on deploying yolov8 on jetson TX2 using docker? I am pulling images docker pull ultralytics/ultralytics:latest-jetson terminal will downloading pause, long time pulling images unsuccessful, repeated attempts still so, any solution please?

    3. Paula DerrengerUltralytics(изменено)

      @HWKevinhwk hey there! 😊

      It sounds like you're facing issues with the Docker image pull for the Jetson TX2. This might be due to network issues or Docker Hub delays, or to using a tag that does not exist.

      Here's a simplified breakdown to get you started on the TX2 using Docker:

      1. Ensure JetPack is installed: The TX2 is supported on JetPack 4, which includes the GPU drivers necessary for Docker integration with the Jetson GPU.

      2. Install Docker:

        sudo apt-get install docker.io
      3. NVIDIA runtime support (JetPack should handle this): nvidia-smi doesn't work on Jetson, so verify the nvidia runtime with docker info | grep -i runtime.

      4. Pull the Docker image for Jetson. Pulling large Docker images can be challenging on slower networks:

        sudo docker pull ultralytics/ultralytics:latest-jetson-jetpack4

        If you keep facing issues while pulling the image, try restarting your Docker service or check your network settings. Sometimes, using a different network can help too!

      5. Run the Image:

        sudo docker run -it --ipc=host --runtime=nvidia ultralytics/ultralytics:latest-jetson-jetpack4

      This should set you on the right path to running Ultralytics YOLO on your Jetson TX2. If the problem persists, it might be worth checking Docker's log or discussing this issue further with your network admin or on Docker forums! 😄

      Happy coding! 🚀

  4. Peter-codingGitHub

    Hey! I trained a YOLOv8 model on my local computer. I have the best.pt file, and I can use it in CLI (conda) for predict. I want to make a python app, which uses this best.pt file, and I want to containerize it. Is it possible to write the full python app (it is just a few lines of code, which runs the detection, then writes the detection result to a database), then containerize it, and able to use it anywhere? Thank you! :D

    1. Paula DerrengerUltralytics

      Hey there! 😊

      Absolutely, you can absolutely containerize your Python app that uses the best.pt model! Here's a quick guide:

      1. Create Your Python App: Just like you mentioned, write your Python code that performs the detection and interacts with the database.

      2. Dockerize Your Application:

        • Dockerfile: Create a Dockerfile in your project directory. Here's a simple example that uses Ultralytics' Docker image as a base:

          FROM ultralytics/ultralytics:latest
          WORKDIR /app
          COPY . /app
          RUN pip install -r requirements.txt  # Assuming you have a requirements.txt
          CMD ["python", "your_script.py"]
        • Build Your Docker Image: Run the following command in your project directory:

          sudo docker build -t your-app-name .
        • Run Your Container: To run your container, especially if you're planning to use GPU, you might want to specify --gpus all:

          sudo docker run -it --ipc=host --gpus all your-app-name

          For accessing local files, consider mounting a volume as described in the Docker Quickstart Guide.

      3. Deployment: With your Docker image built, you can now deploy and run it anywhere that Docker is supported. If using a GPU, ensure the host machine supports NVIDIA GPUs and has the necessary drivers and Docker configured correctly.

      That's it! You should be able to use your model within a containerized app now. If you hit any snags, double-check the Docker Quickstart Guide for Ultralytics for more details. Happy coding! 😄

  5. udayzee05GitHub

    DEPRECATION NOTICE The nvidia-docker wrapper is no longer supported, and the NVIDIA Container Toolkit has been extended to allow users to configure Docker to use the NVIDIA Container Runtime. For further instructions, see the NVIDIA Container Toolkit documentation and specifically the install guide.22 Jan 2024

    1. Paula DerrengerUltralytics(изменено)

      Hey there! 👋 Thanks for bringing up the deprecation notice regarding the nvidia-docker wrapper. You're right; use the NVIDIA Container Toolkit for GPU support in Docker containers. Here's how to set it up on Ubuntu/Debian, as described in our Docker Quickstart Guide:

      # Add the NVIDIA Container Toolkit repository
      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
      
      # Install the NVIDIA Container Toolkit
      sudo apt-get update
      sudo apt-get install -y nvidia-container-toolkit

      And to verify that the GPU devices are available to Docker:

      nvidia-ctk cdi list

      This should list entries such as nvidia.com/gpu=all, indicating that your Docker setup can leverage GPU acceleration. 🚀

      For more detailed instructions and tips on using Ultralytics with Docker, including mounting local directories and running containers, check out our Docker Quickstart Guide. Happy coding!