症状

docker build 実行時に no space left on device エラーが表示され、ビルドが失敗する。

結論：まずこれを確認

  1. docker system df でDockerが使用している容量を確認
  2. docker system prune -a で不要なリソースを削除
  3. それでも解決しない場合は /var/lib/docker のディスク容量を確認

トラブルシューティングフロー

    flowchart TD
    A[no space left on device] --> B{docker system df を確認}
    B -->|使用量が多い| C[docker system prune を実行]
    B -->|使用量が少ない| D[ホストのディスク容量を確認]
    C --> E{解決した?}
    E -->|Yes| F[完了]
    E -->|No| G[ビルドキャッシュを削除]
    G --> H{解決した?}
    H -->|Yes| F
    H -->|No| D
    D --> I{空き容量あり?}
    I -->|No| J[不要ファイルを削除/ディスク拡張]
    I -->|Yes| K[Docker data-root を確認]

よくある原因

  • 未使用イメージの蓄積 - 古いイメージが削除されずに残っている
  • ビルドキャッシュの肥大化 - 中間レイヤーがキャッシュとして大量に残っている
  • 停止コンテナの残存 - 停止したコンテナがディスクを消費し続けている
  • 未使用ボリュームの蓄積 - データボリュームが削除されずに残っている
  • ホストディスクの容量不足 - Docker以外のファイルでディスクが圧迫されている
  • Docker data-root の設定ミス - 容量の少ないパーティションにDockerデータが配置されている
  • マルチステージビルドの中間イメージ - ビルド途中のイメージがキャッシュに残っている

確認手順

ステップ1: Dockerのディスク使用状況を確認する

    docker system df

🔍 チェックポイント: RECLAIMABLE の値が大きければ、削除可能なリソースが多い

詳細を確認する場合：

    docker system df -v

ステップ2: 不要なリソースを一括削除する

停止コンテナ、未使用ネットワーク、dangling イメージを削除：

    docker system prune

未使用イメージもすべて削除する場合：

    docker system prune -a

🔍 チェックポイント: 削除後に docker system df で使用量が減少していることを確認

ステップ3: ビルドキャッシュを削除する

    docker builder prune

すべてのビルドキャッシュを削除：

    docker builder prune -a

🔍 チェックポイント: Total reclaimed space で削除された容量を確認

ステップ4: ボリュームを確認・削除する

未使用ボリュームの一覧：

    docker volume ls -f dangling=true

未使用ボリュームを削除：

    docker volume prune

🔍 チェックポイント: 削除前に必要なデータが含まれていないか確認

ステップ5: ホストのディスク容量を確認する

    df -h

Dockerのデータディレクトリの容量を確認：

    df -h /var/lib/docker

🔍 チェックポイント: /var/lib/docker が配置されているパーティションの空き容量を確認

ステップ6: Docker data-root の設定を確認する

    docker info | grep "Docker Root Dir"

🔍 チェックポイント: 出力されたパスが十分な容量を持つパーティションにあるか確認

NG行動（やってはいけないこと）

  • /var/lib/docker を直接削除する - Dockerの状態が不整合になり、再起動後に起動しなくなる
  • docker system prune -a --volumes を確認なしで実行する - 必要なボリュームデータも削除される
  • ビルド中に prune を実行する - ビルドが失敗する可能性がある
  • root パーティションが満杯の状態で放置する - システム全体が不安定になる

よくある質問（FAQ）

Q1: prune しても容量が回復しない場合は？

A: docker info | grep "Docker Root Dir" で確認し、そのディレクトリのパーティション自体の空き容量を df -h で確認する。Docker以外のファイルが原因の可能性がある。

Q2: 特定のイメージだけ削除したい場合は？

A: docker images で一覧を確認し、docker rmi <イメージID> で個別に削除する。依存関係がある場合は -f オプションが必要になることがある。

Q3: WSL2環境で容量が回復しない場合は？

A: WSL2のvhdxファイルは自動で縮小されない。PowerShellで wsl --shutdown 後、Optimize-VHD または diskpart で手動で縮小する。

関連するエラー・症状

  • （関連記事準備中）
  • （関連記事準備中）
  • （関連記事準備中）

解決しない場合

  • 公式ドキュメント: Docker object pruning
  • 確認すべきログ: journalctl -u docker.service（Linux）
  • 次に調べるキーワード: docker overlay2 cleanup, docker storage driver, docker data-root 移動