Краткое руководство по Docker для Ultralytics#
Это руководство подробно объясняет, как настроить Docker-среду для проектов Ultralytics. Docker — это платформа для разработки, доставки и запуска приложений в контейнерах. Она особенно полезна тем, что гарантирует одинаковую работу программ независимо от места их развёртывания. Подробнее см. в репозитории Ultralytics на Docker Hub.
Что ты узнаешь#
- Настройка 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 updatesudo 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.
| Тег | Платформа и назначение | Источник |
|---|---|---|
latest | Linux AMD64 с CUDA для обучения и инференса на GPU | Dockerfile |
latest-export | Linux AMD64 с CUDA и зависимостями для экспорта, конвертации и тестирования производительности | Dockerfile-export |
latest-amd | Linux AMD64 с ROCm и MIGraphX для обучения и инференса на GPU AMD | Dockerfile-amd |
latest-python | Облегчённый образ Linux AMD64 с Python 3.14 для инференса на CPU | Dockerfile-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 и обучающими блокнотами Ultralytics | Dockerfile-jupyter |
latest-arm64 | Образ Linux ARM64 с Python 3.13 и CPU для Apple silicon, Raspberry Pi и других систем ARM64 | Dockerfile-arm64 |
latest-nvidia-arm64 | Linux ARM64 для DGX Spark (DGX OS) и PyTorch на Thor (JetPack 7.1); встроенный TensorRT не поддерживает JetPack | Dockerfile-nvidia-arm64 |
latest-jetson-jetpack6 | Linux ARM64 для устройств NVIDIA Jetson под управлением JetPack 6 | Dockerfile-jetson-jetpack6 |
latest-jetson-jetpack5 | Linux ARM64 для устройств NVIDIA Jetson под управлением JetPack 5 | Dockerfile-jetson-jetpack5 |
latest-jetson-jetpack4 | Linux ARM64 для устройств NVIDIA Jetson под управлением JetPack 4 | Dockerfile-jetson-jetpack4 |
latest-runner | Образ Linux AMD64 с CUDA для собственного раннера GitHub Actions с GPU | Dockerfile-runner |
latest-runner-cpu | Образ Linux AMD64 для собственного раннера GitHub Actions с CPU | Dockerfile-runner-cpu |
В образах AMD64 для GPU (latest, latest-export и latest-runner) используются PyTorch 2.14 и CUDA 13.2. Перед запуском проверь поддержку CUDA драйвером хост-системы с помощью nvidia-smi; установка более нового контейнера не обновляет драйвер хоста. В CUDA 13 прекращена поддержка GPU Maxwell, Pascal и Volta, включая Tesla P100 и V100. См. примечания к выпуску CUDA от NVIDIA и требования к совместимости драйверов.
В образе NVIDIA ARM64 используются NVIDIA PyTorch 26.08, CUDA 13.4 и TensorRT 11.2. Поддержка Thor в PyTorch не распространяется на TensorRT: NVIDIA не поддерживает TensorRT 11.2 в JetPack. Для экспорта TensorRT на Jetson используй поддерживаемую среду выполнения TensorRT 10.x для своей версии JetPack. Соблюдай требования платформы из руководства по Jetson или руководства по DGX Spark. В образах для JetPack 4, 5 и 6 сохраняются отдельные стеки для соответствующих устройств.
Dockerfile для Conda доступен для локальной сборки; автоматическая публикация latest-conda отключена, поэтому этот тег в реестре не содержит этих обновлений.
Для экспорта LiteRT используй latest-python-export. В образе GPU latest-export остаётся PyTorch 2.14, а LiteRT отсутствует, поскольку текущая версия его зависимости требует PyTorch ниже 2.14.
В образах 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#
Вот как запустить контейнер Docker с Ultralytics:
Использование только 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).
В 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 сопряжена с потенциальными рисками безопасности. Поэтому рекомендуется тестировать это решение только в контролируемой среде. Дополнительную информацию о том, как использовать xhost(1)(2), см. в этих материалах.
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. Можно также установить эти программы в контейнер Docker Ultralytics и проверить доступ к серверу X11 графического сервера GNU/Linux. Если возникнут проблемы, попробуй задать переменную окружения -e QT_DEBUG_PLUGINS=1. Эта переменная окружения включает вывод отладочной информации, которая поможет устранить неполадки.
После завершения работы с графическим интерфейсом Docker#
В обоих случаях не забудь отозвать доступ группы Docker, когда закончишь.
xhost -local:dockerХочешь просматривать результаты обработки изображений прямо в терминале?
См. руководство по просмотру результатов обработки изображений в терминале
Теперь всё готово к использованию Ultralytics с Docker — можно воспользоваться всеми возможностями решения. Чтобы разместить веб-приложение Ultralytics на собственном сервере, см. руководство по локальному развёртыванию платформы. Альтернативные способы установки пакета Python описаны в документации Ultralytics по быстрому старту.
Часто задаваемые вопросы#
Чтобы настроить Ultralytics с Docker, сначала убедись, что Docker установлен в системе. Если у тебя есть GPU NVIDIA, установи NVIDIA Container Toolkit, чтобы включить поддержку GPU. Затем получи последний образ Docker Ultralytics из Docker Hub с помощью следующей команды:
sudo docker pull ultralytics/ultralytics:latestПодробные инструкции см. в руководстве по быстрому старту с Docker.
Образы Docker Ultralytics обеспечивают одинаковую среду на разных компьютерах, воспроизводя один и тот же набор программ и зависимостей. Это особенно полезно для совместной работы команд, запуска моделей на разном оборудовании и обеспечения воспроизводимости. Используй
latestдля обычного обучения на GPU NVIDIA или выбери образ, соответствующий версии JetPack для устройства NVIDIA Jetson. См. полную таблицу образов или изучи Docker Hub Ultralytics.Сначала убедись, что NVIDIA Container Toolkit установлен и настроен. Затем выполни следующую команду, чтобы запустить Ultralytics YOLO с поддержкой GPU:
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUsЭта команда запускает контейнер Docker с доступом к GPU. Дополнительную информацию см. в руководстве по быстрому старту с Docker.
Чтобы визуализировать результаты предсказаний 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— на нужный путь внутри контейнера. Такая настройка позволяет работать с локальными файлами из контейнера. Дополнительную информацию см. в разделе «Примечание о доступе к файлам».