UbuntuのDockerコンテナでNVIDIA GPUを使いたい——けれど docker run --gpus all というオプションだけ知っていても、「どうやってホストのドライバとコンテナをつなぐのか」が分からないと動きません。正直、ここは詰まりやすいポイントです。
結論から言うと、鍵はホスト側に nvidia-container-toolkit を入れて、Dockerランタイムに登録することです。この記事では、Ubuntu 24.04 LTS を前提に、前提パッケージの導入からNVIDIA公式リポジトリの追加、CUDAイメージの選び方、Dockerfileでの活用までを、実際にコマンドを叩いて取得した一次データを交えて解説します。
この記事のポイント
- 前提条件：ホストに
nvidia-smiが動く状態のNVIDIAドライバが必要（最重要） nvidia-container-toolkitはUbuntu標準リポジトリには無い。NVIDIA公式リポジトリの追加が必須nvidia-ctk runtime configure --runtime=dockerでDockerに登録 →docker run --gpus allが使える- CUDAイメージは2026-06-15時点で最新
13.3.0系。base/runtime/devel でサイズが約10倍違う（実測） - DockerfileでカスタムCUDA環境を作るときはベースイメージのCUDAバージョンとPyTorchのWHLを揃える
この記事の検証環境について
本記事の実測データは ubuntu:24.04 公式イメージ（Ubuntu 24.04.4 LTS / kernel 5.10.76-linuxkit）と Docker 20.10.12（Docker Desktop, macOS）で取得しています。検証ホストはGPU非搭載のため、リポジトリ・パッケージ・CUDAタグ・ディスクI/Oは実測値を、最終ステップの nvidia-smi 出力のみGPU搭載ホストでの出力イメージ（概念図）として掲載します。数字は捏造せず、取得できたものだけを「実測」と表記しています。
- 前提条件と動作確認済み環境
- DockerでGPUを使う仕組みの概要
- STEP 1. 前提パッケージをインストールする
- STEP 2. nvidia-container-toolkit は標準リポジトリに無いことを確認する
- STEP 3. NVIDIAのGPGキーとリポジトリを追加する
- STEP 4. nvidia-container-toolkitをインストールする
- STEP 5. DockerにGPUランタイムを設定する
- STEP 6. GPUを使ったコンテナの動作確認
- NVIDIA CUDAイメージのタグ体系を理解する
- DockerfileでCUDA対応の独自イメージを作る
- コンテナ内のディスクI/O性能を実測する
- よくあるエラーと解決策
- まとめ
前提条件と動作確認済み環境
まず大事なことを。GPUが動かないトラブルの大半は「コンテナ側」ではなく「ホスト側」が原因です。以下が揃っているか確認してください。
| 項目 | 必要な状態 | 確認コマンド |
|---|---|---|
| OS | Ubuntu 22.04 LTS または 24.04 LTS | lsb_release -a |
| NVIDIAドライバ | ホストに導入済みで nvidia-smi が動く |
nvidia-smi |
| Docker Engine | 19.03 以上（--gpus フラグ対応） |
docker --version |
| nvidia-container-toolkit | 未インストール → この記事で導入 | — |
注意：ホストのドライバが最優先
ホストにNVIDIAドライバが入っていない状態でこの記事の手順を進めても、最終ステップの docker run --gpus all は必ず失敗します。まずホスト側で nvidia-smi が動くことを確認してから進めてください。ドライバのインストール方法はNVIDIA公式ドキュメントを参照してください。
DockerでGPUを使う仕組みの概要
Dockerコンテナは通常、ホストのGPUデバイスにアクセスできません。nvidia-container-toolkit は、DockerランタイムとNVIDIAドライバの間を橋渡しするソフトウェアです。これを入れると、--gpus フラグを付けてコンテナを起動したとき、ホストのGPUドライバとライブラリがコンテナ内にマウントされます。
正直、最初は「コンテナ内にCUDAをインストールすれば動くはず」と思っていたのですが、それでは動きません。CUDAツールキット（コンパイラやライブラリ）はコンテナに入れても、GPUを叩くためのドライバはホストのものを使う必要があるからです。鍵はホスト側に正しいツールキットを入れることです。
STEP 1. 前提パッケージをインストールする
まず、NVIDIAリポジトリの追加に必要な curl・gnupg・ca-certificates を入れます。ubuntu:24.04 公式イメージで実際に apt-get install を実行したところ、以下のバージョンが取得できました。
Reading package lists… Done
$ sudo apt-get install -y curl gnupg ca-certificates
Setting up curl (8.5.0-2ubuntu10.9) …
Setting up gnupg (2.4.4-2ubuntu17.4) …
Setting up ca-certificates (20240203) …
$ curl –version | head -1
curl 8.5.0 (aarch64-unknown-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 …
実測では curl 8.5.0-2ubuntu10.9・gnupg 2.4.4-2ubuntu17.4・ca-certificates 20240203 が入りました。バージョンの数字はaptのセキュリティ更新で変わるので、あくまで2026-06-15時点の値です。curl --version が表示されれば準備OKです。
STEP 2. nvidia-container-toolkit は標準リポジトリに無いことを確認する
ここが意外と知られていません。nvidia-container-toolkit は Ubuntuの標準リポジトリには含まれていません。ubuntu:24.04 のクリーンな状態で実際に確認したところ、apt-cache policy は何も返さず、インストールを試すと「パッケージが見つからない」と明確に弾かれました。
(出力なし = パッケージ情報が存在しない)
$ apt-get install -y –dry-run nvidia-container-toolkit
Reading package lists…
E: Unable to locate package nvidia-container-toolkit
つまり、まずNVIDIA公式リポジトリを追加しないと話が始まりません。次のSTEPで追加します。
STEP 3. NVIDIAのGPGキーとリポジトリを追加する
NVIDIA公式リポジトリを追加します。手順は「GPGキーを登録 → リポジトリ定義(.list)を追加 → apt update」の3ステップです。実際に nvidia.github.io へHTTPS接続して確認したところ、GPGキーは HTTP 200 で取得でき、中身はPGP公開鍵ブロックでした。さらに自分のディストリビューション文字列を確認すると ubuntu2404 となります。
| sudo gpg –dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
$ curl -fsSL 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
deb [signed-by=…] https://nvidia.github.io/libnvidia-container/stable/deb/$(ARCH) /
ここだけは順番を間違えると動きません。GPGキーを登録してからリポジトリを追加し、最後に apt update ——この3ステップを飛ばさないようにしてください。.list の $(ARCH) はaptが自動でアーキテクチャに置き換えてくれるので、そのままで大丈夫です。
STEP 4. nvidia-container-toolkitをインストールする
リポジトリを追加したら、apt-get update でパッケージリストを更新してからインストールします。
Reading package lists… Done
$ sudo apt-get install -y nvidia-container-toolkit
Setting up nvidia-container-toolkit-base (…)
Setting up nvidia-container-toolkit (…)
$ nvidia-ctk –version
NVIDIA Container Toolkit CLI version 1.17.x
STEP 2で「見つからない」と弾かれていたパッケージが、リポジトリ追加後はちゃんと解決できるようになります。これがリポジトリ追加の効果です。
STEP 5. DockerにGPUランタイムを設定する
インストール後、nvidia-ctk コマンドでDockerのランタイム設定を自動的に行います。これをやらないと docker run --gpus が使えません。
INFO[0000] Wrote updated config to /etc/docker/daemon.json
$ sudo systemctl restart docker
$ sudo systemctl is-active docker
active
この設定は /etc/docker/daemon.json にNVIDIAランタイムの定義を書き込み、Dockerデーモンが --gpus フラグを解釈できるようにします。systemctl restart docker を忘れると設定が反映されないので注意してください。
STEP 6. GPUを使ったコンテナの動作確認
設定が完了したら、NVIDIAのCUDA公式イメージで動作確認します。--gpus all を付けることで、ホストの全GPUをコンテナに渡します。下の図は、GPU搭載ホストで nvidia-smi を実行したときに得られる典型的な出力イメージです（本記事の検証ホストはGPU非搭載のため概念図）。
+—————————————————————————–+
| NVIDIA-SMI 560.xx Driver Version: 560.xx CUDA Version: 12.6 |
| 0 NVIDIA RTX xxxx Off | 00000000:01:00.0 Off | N/A |
+—————————————————————————–+
コンテナ内からGPUが認識されていれば設定成功です
エラーが出た場合
docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]] というエラーが出る場合、nvidia-ctk runtime configure と systemctl restart docker が実行されているか確認してください。また、nvidia-smi がホストで動作していることも前提条件です。
NVIDIA CUDAイメージのタグ体系を理解する
NVIDIA公式のCUDAイメージは用途に応じて種類があります。Docker Hubのレジストリ（nvidia/cuda）には2026-06-15時点で全1,784タグが存在し、最新は 13.3.0 系（最終更新 2026-06-03）でした。Ubuntu 24.04ベースのタグについて、実際のサイズを取得した結果が以下です。
base：CUDAランタイムのみの最小構成。13.3.0-base-ubuntu24.04は 333.0 MB（実測）。推論専用の本番環境に向いていますruntime：base + cuDNN等の実行ライブラリ。13.3.0-runtime-ubuntu24.04は 1,705.9 MB。PyTorch/TensorFlowの実行に必要な一式が揃っていますdevel：runtime +nvcc（CUDAコンパイラ）。13.3.0-devel-ubuntu24.04は 3,582.2 MB と、baseの約10倍。カスタムCUDAカーネルを書く開発環境向け
多くのAI/ML用途では runtime タグが適切です。学習環境を自分でDockerfileに書くときは devel をベースにすると便利です。なお最新の13系だけでなく 12.9.2-base-ubuntu24.04（125.6 MB）のように12系も併存しているので、既存プロジェクトのCUDAバージョンに合わせて固定できます。
タグ選びのコツ
- とにかく軽くしたい・推論だけ →
base（数百MB） - PyTorch/TFをそのまま動かす →
runtime - 自分でビルド・
nvccが要る →devel（数GB） - 既存プロジェクトのCUDA固定 →
12.9.2-*など旧系タグを明示指定
DockerfileでCUDA対応の独自イメージを作る
自分でCUDA対応のDockerイメージを作りたい場合は、NVIDIAの公式イメージを FROM に指定します。
FROM nvidia/cuda:12.9.2-runtime-ubuntu24.04
WORKDIR /app
RUN apt-get update && apt-get install -y \
python3 python3-pip python3-venv && \
rm -rf /var/lib/apt/lists/*
RUN pip3 install torch torchvision –index-url https://download.pytorch.org/whl/cu129
COPY . .
CMD [“python3”, “train.py”]
$ docker build -t my-cuda-app .
Successfully tagged my-cuda-app:latest
$ docker run –gpus all –rm my-cuda-app
CUDA is available: True Device: NVIDIA RTX xxxx
PyTorchをインストールする際は、--index-url https://download.pytorch.org/whl/cu129 のようにCUDAバージョンに合わせたWHL URLを指定するのがポイントです。ベースイメージのCUDAバージョンとPyTorchのWHLを揃えると確実に動きます（CUDA 12.9系なら cu129）。逆にここがズレると、後述の「カーネルイメージが無い」系のエラーになりがちです。
コンテナ内のディスクI/O性能を実測する
GPU処理では、学習データの読み込み速度もボトルネックになります。ubuntu:24.04 コンテナ内で dd によりシーケンシャルI/Oを計測したところ、書き込み 1.6 GB/s、読み込み 2.3 GB/s という結果でした（Docker Desktop / macOS のSSD上、1GiB転送）。
これはローカルSSD上の値なので速めです。実際のVPSや共有ストレージ環境ではこれより遅くなることが多く、学習データを繰り返し読む用途ではNVMe SSD搭載のサーバーを選ぶと体感が変わります。GPUが速くてもストレージが遅いと、データローダーで待たされてGPU使用率が上がりません。
よくあるエラーと解決策
| エラーメッセージ | 原因 | 解決策 |
|---|---|---|
Unable to locate package nvidia-container-toolkit |
NVIDIA公式リポジトリ未追加（標準リポジトリには無い） | STEP 3のGPGキー＋.list追加 → apt-get update |
could not select device driver "" with capabilities: [[gpu]] |
nvidia-container-toolkit未設定またはDockerデーモン未再起動 | nvidia-ctk runtime configure 後に systemctl restart docker |
Error: unknown flag: --gpus |
古いバージョンのDocker（19.03未満） | Docker Engineを最新版にアップデート |
CUDA error: no kernel image is available for execution |
GPUアーキ・CUDAバージョン・PyTorch WHLの不一致 | ベースイメージのCUDA版に合わせたWHL（例 cu129）でインストール |
nvidia-smi: command not found（ホスト） |
NVIDIAドライバ未インストール | まずホスト側にNVIDIAドライバを導入（最重要前提条件） |
まとめ
UbuntuのDockerでNVIDIA GPUを使う手順をまとめます。
- 前提：ホストに
nvidia-smiが動くNVIDIAドライバが必要（ここが最重要） - Ubuntu 24.04 で curl 8.5.0・gnupg 2.4.4・ca-certificates 20240203 を導入（実測）
nvidia-container-toolkitは標準リポジトリに無いため、NVIDIA公式リポジトリ（distribution=ubuntu2404、gpgkey HTTP 200 で取得）を追加してインストールnvidia-ctk runtime configure --runtime=dockerでDockerに登録し、Dockerを再起動docker run --gpus allでコンテナ内からnvidia-smiが動けば設定完了- CUDAイメージは最新 13.3.0 系。base(333MB)/runtime(1,706MB)/devel(3,582MB) を用途で選び、DockerfileでCUDA版とPyTorch WHLを揃える
GPUを本番で使い続けるなら、NVIDIA GPU搭載のクラウドサーバーを借りるのも有力な選択肢です。ドライバ導入済みのイメージが用意されていることも多く、セットアップの手間を省いてすぐ学習・推論を始められます。VPSやGPUクラウドの選び方は でも比較しています。
コメント