Ultralytics YOLO27:

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の検出結果を表示する方法
  • ローカルディレクトリをコンテナにマウントする方法


Watch: How to Get started with Docker | Usage of Ultralytics Python Package inside Docker live demo 🎉

前提条件#

  • システムにDockerがインストールされていることを確認してください。インストールされていない場合は、DockerのWebサイトからダウンロードしてインストールできます。
  • GPUアクセラレーションを使用する場合は、システムにNVIDIA GPUとNVIDIAドライバーがインストールされていることを確認してください。CPUイメージではNVIDIAハードウェアは必要ありません。
  • NVIDIA Jetsonデバイスを使用している場合は、適切なJetPackバージョンがインストールされていることを確認してください。詳細については、NVIDIA Jetsonガイドを参照してください。

NVIDIAサポート付きでDockerをセットアップする（オプション）#

まず、次のコマンドを実行して、NVIDIAドライバーが適切にインストールされていることを確認します。

nvidia-smi

NVIDIA Container Toolkitのインストール#

次に、DockerコンテナでGPUサポートを有効にするため、NVIDIA Container Toolkitをインストールします。

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のnvidia-cdi-refreshサービスは、Toolkit >= 1.18では仕様を自動的に生成および管理します）。

nvidia-ctk cdi list

nvidia.com/gpu=0やnvidia.com/gpu=allなどのエントリが表示されます。検出されたCDIデバイスはdocker infoにも表示されます。

Ultralytics Dockerイメージのインストール#

Ultralyticsは、次のイメージをDocker Hubに公開しています。各イメージは、Docker公開ワークフローによって、リンク先のDockerfileからビルドされます。

タグプラットフォームと用途ソース
latestGPUトレーニングおよび推論用のCUDA対応Linux AMD64Dockerfile
latest-export変換およびベンチマーク用のCUDA・エクスポート依存関係対応Linux AMD64Dockerfile-export
latest-pythonCPU推論用の軽量Linux AMD64 PythonイメージDockerfile-python
latest-python-exportエクスポート依存関係を含むLinux AMD64 CPUイメージDockerfile-python-export
latest-cpuデフォルトコマンドとしてBashを使用するLinux AMD64 CPUイメージDockerfile-cpu
latest-jupyterJupyterLabとUltralyticsチュートリアルノートブックを含むLinux AMD64 CPUイメージDockerfile-jupyter
latest-arm64Appleシリコン、Raspberry Pi、その他のARM64システム向けLinux ARM64 CPUイメージDockerfile-arm64
latest-nvidia-arm64Linux ARM64はDGX Spark (DGX OS)およびThorのPyTorch (JetPack 7.1)に対応しています。バンドルされているTensorRTはJetPackをサポートしていません。Dockerfile-nvidia-arm64
latest-jetson-jetpack6JetPack 6を実行するNVIDIA Jetsonデバイス向けLinux ARM64Dockerfile-jetson-jetpack6
latest-jetson-jetpack5JetPack 5を実行するNVIDIA Jetsonデバイス向けLinux ARM64Dockerfile-jetson-jetpack5
latest-jetson-jetpack4JetPack 4を実行するNVIDIA Jetsonデバイス向けLinux ARM64Dockerfile-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では、Tesla P100やV100を含め、Maxwell、Pascal、Volta GPUのサポートが削除されます。NVIDIAのCUDAリリースノートおよびドライバの互換性要件を参照してください。

NVIDIA ARM64イメージは、CUDA 13.4およびTensorRT 11.2を搭載したNVIDIA PyTorch 26.08を使用します。ThorにおけるPyTorchサポートはTensorRTには及びません。NVIDIAはJetPack上でTensorRT 11.2をサポートしていません。JetsonのTensorRTエクスポートには、使用するJetPackリリースに対応するサポート済みのTensorRT 10.xランタイムを使用してください。JetsonガイドまたはDGX Sparkガイドのプラットフォーム要件に従ってください。JetPack 4、5、6のイメージは、それぞれ個別のデバイス固有のスタックを維持します。

CondaのDockerfileはローカルビルド用に入手可能です。latest-conda の自動パブリッシングは無効化されているため、そのレジストリタグにはこれらのアップデートが含まれていません。

LiteRTのエクスポートには latest-python-export を使用してください。GPUの latest-export イメージはPyTorch 2.14を維持し、現在の依存関係がPyTorch 2.14未満を必要とするためLiteRTを除外しています。

latestで始まるタグは、直近に公開されたmainブランチのビルドを追跡します。バージョン付きタグでは、latestプレフィックスがVERSION、VERSION-cpu、VERSION-jetson-jetpack6などのUltralyticsリリースに置き換えられます。再現可能な環境には、バージョン付きタグを使用してください。

最新のイメージをプルするには、次のコマンドを実行します。

# 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を割り当て、stdinを開いたままにするため、コンテナと対話できます。--ipc=hostフラグはホストのIPC名前空間の共有を有効にします。これはプロセス間でメモリを共有するために不可欠です。--device nvidia.com/gpu=...フラグは、CDIを介してコンテナからホストのGPUにアクセスできるようにします。

`--gpus all`の代わりにCDIを使用する

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サポートでは、NVIDIA CDIデバイスを利用できないため、現在はWSL 2バックエンドで--gpus allを使用しています。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）アプリケーションを実行する#

非常に実験的な機能 - すべてのリスクはユーザーが負うものとします

以下の手順は実験的なものです。X11ソケットをDockerコンテナと共有すると、セキュリティ上の潜在的なリスクが生じます。そのため、このソリューションは管理された環境でのみテストすることを推奨します。詳細については、xhostの使用方法に関する次のリソースを参照してください(1)(2)。

Dockerは主にバックグラウンドアプリケーションやCLIプログラムのコンテナ化に使用されますが、グラフィカルプログラムも実行できます。Linux環境では、グラフィカル表示を処理する主なグラフィックサーバーが2つあります。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を使用する#

これで、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クイックスタートドキュメントを参照してください。

FAQ#

  • 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

    詳細については、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-jocher20RAraimbekovm3ONonuralpszr3RIRizwanMunawar2AMambitious-octopus1PDpderrenger1SHSHOscarChen1PIpicsalex1LAlakshanthad1FRFruchtzwerg941BUBurhan-Q1JPJpfonseca1

コメント