Ultralytics Docker クイックスタートガイド#
このガイドでは、Ultralytics プロジェクト用の Docker 環境をセットアップする方法を詳しく説明します。Docker は、コンテナ内でアプリケーションを開発、配布、実行するためのプラットフォームです。特に、デプロイ先にかかわらずソフトウェアが常に同じように動作することを保証するうえで役立ちます。詳細については、Docker Hub の Ultralytics Docker リポジトリをご覧ください。
このガイドで学べること#
- NVIDIA サポートを有効にした Docker のセットアップ
- Ultralytics Docker イメージのインストール
- CPU または GPU を使用して Docker コンテナ内で Ultralytics を実行する
- Docker でディスプレイサーバーを使用して Ultralytics の検出結果を表示する
- ローカルディレクトリをコンテナにマウントする
視聴: Docker の始め方 | Docker 内で Ultralytics Python パッケージを使うライブデモ 🎉
前提条件#
- システムに Docker がインストールされていることを確認してください。インストールされていない場合は、Docker のウェブサイトからダウンロードしてインストールできます。
- GPU アクセラレーションを利用するには、システムに NVIDIA GPU とNVIDIA ドライバーがインストールされていることを確認してください。CPU イメージには NVIDIA ハードウェアは必要ありません。
- NVIDIA Jetson デバイスを使用する場合は、適切なバージョンの JetPack がインストールされていることを確認してください。詳細については、NVIDIA Jetson ガイドをご覧ください。
NVIDIA サポートを有効にした Docker のセットアップ（任意）#
まず、次のコマンドを実行して、NVIDIA ドライバーが正しくインストールされていることを確認します。
nvidia-smiNVIDIA 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 updatesudo apt-get install -y nvidia-container-toolkitDocker で CDI デバイスを確認する#
nvidia-ctk cdi list を実行して、GPU の CDI デバイスが利用可能であることを確認します（ツールキットの nvidia-cdi-refresh サービスは、ツールキット >= 1.18 で仕様を自動的に生成、管理します）。
nvidia-ctk cdi listnvidia.com/gpu=0 や nvidia.com/gpu=all などのエントリが表示されます。検出された CDI デバイスは docker info にも表示されます。
Ultralytics Docker イメージのインストール#
Ultralytics は、次のイメージをDocker Hubに公開しています。各イメージは、リンク先の Dockerfile からDocker 公開ワークフローによってビルドされます。
| タグ | プラットフォームと用途 | ソース |
|---|---|---|
latest | GPU トレーニングおよび推論向けの CUDA 対応 Linux AMD64 イメージ | Dockerfile |
latest-export | 変換およびベンチマーク向けの、CUDA とエクスポート用依存関係を含む Linux AMD64 イメージ | Dockerfile-export |
latest-amd | AMD GPU のトレーニングおよび推論向けの、ROCm と MIGraphX を備えた Linux AMD64 イメージ | 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-cpu | デフォルトコマンドに Bash を使用する Linux AMD64 CPU イメージ | Dockerfile-cpu |
latest-jupyter | JupyterLab と Ultralytics のチュートリアルノートブックを含む Linux AMD64 CPU イメージ | Dockerfile-jupyter |
latest-arm64 | Apple silicon、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 は JetPack に対応していません。 | Dockerfile-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 では、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 は含まれていません。
Python、CPU、Jupyter、および CPU runner の各イメージは Python 3.14 を使用します。Python エクスポートイメージは、latest-python-3.13 ベースを使用します。このベースは、TensorFlow、CoreML、PaddlePaddle がまだ Python 3.14 をサポートしていないため、--build-arg PYTHON_VERSION=3.13 を含む同じ Dockerfile-python からビルドされています。
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-cpuGPU を使用する#
# 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）にアクセスできます。
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）アプリケーションを実行する#
Dockerは主にバックグラウンドアプリケーションやCLIプログラムのコンテナ化に使用されますが、GUIプログラムも実行できます。Linuxでは、グラフィカル表示を処理する主要なディスプレイサーバーが2つあります。X11（Xウィンドウシステムとも呼ばれます）と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 GUIの使用後#
どちらの場合も、作業が終わったらDockerグループからのアクセス権を忘れずに取り消してください。
xhost -local:docker画像の結果をターミナルで直接表示しますか？
ターミナルを使用して画像の結果を表示する方法については、次のガイドをご覧ください。
これで、DockerでUltralyticsを使用する準備が整い、その機能を活用できます。Ultralytics Webアプリケーションをセルフホストするには、オンプレミスプラットフォームガイドをご覧ください。Pythonパッケージの別のインストール方法については、Ultralyticsクイックスタートドキュメントをご覧ください。
よくある質問#
DockerでUltralyticsをセットアップするには、まずシステムにDockerがインストールされていることを確認してください。NVIDIA GPUをお持ちの場合は、GPUサポートを有効にするためにNVIDIA Container Toolkitをインストールしてください。次に、以下のコマンドを使用して、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:latestWaylandを実行しているシステムでは、次を使用します。
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）アプリケーションを実行するセクションで説明されているように、
show=Trueを使用する前にOpenCVの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をコンテナ内で使用するパスに置き換えてください。この設定により、コンテナ内でローカルファイルを使用できます。詳しくは、ファイルアクセスに関する注意のセクションをご覧ください。