INFRASTRUCTURE2024-11-04📖 3分

Dockerのキャッシュを削除する方法｜Build Cacheの確認・削除・自動化まで解説

Dockerのキャッシュを削除する方法｜Build Cacheの確認・削除・自動化まで解説

Dockerのキャッシュを削除する方法を解説。docker builder pruneによるBuild Cacheの削除から、docker system dfでの確認、cronによる自動化、CI/CDでの運用まで、実務で使えるコマンドと手順をまとめました。

髙木 晃宏

代表 / エンジニア

👨‍💼

「サーバーの容量がまた足りない」——開発チームからそんな報告を受けて調査してみると、原因はDockerのキャッシュだった、という経験はないでしょうか。

Dockerは便利な反面、放置するとビルドキャッシュ（Build Cache）が静かに積み上がり、ディスクを圧迫します。本記事では、Dockerキャッシュの削除方法を、確認・削除・自動化の3ステップで解説します。

Dockerのキャッシュとは？Build Cacheが肥大化する仕組み

Dockerは、イメージをビルドするたびに各レイヤーをキャッシュとして保存します。これは次回以降のビルドを高速化するための仕組みで、開発効率を高めるうえで非常に重要な機能です。

しかし、この便利さには落とし穴があります。アプリケーションの改修を重ねるたびに古いキャッシュレイヤーが蓄積され、使われなくなったDockerキャッシュもディスク上に残り続けるのです。

私自身、以前あるプロジェクトで「なぜかディスクの空き容量が急激に減っている」と感じて調べたところ、ビルドキャッシュだけで数十GBに達していたことがありました。

特に以下のような環境では、Dockerキャッシュの肥大化が深刻になりやすい傾向があります。

  • CI/CDパイプラインで頻繁にビルドを実行している環境
  • 複数のプロジェクトを一台のサーバーで運用しているケース
  • Docker Composeで複数コンテナを管理している開発環境

Dockerキャッシュの使用量を確認する（docker system df）

Dockerのキャッシュを削除する前に、まず現状を把握しましょう。以下のコマンドで、Dockerが使用しているディスク容量の内訳を確認できます。

docker system df

実行すると、以下のように表示されます。

TYPE TOTAL ACTIVE SIZE RECLAIMABLE Images 15 3 4.2GB 3.1GB (73%) Containers 5 2 120MB 80MB (66%) Local Volumes 8 3 2.1GB 1.5GB (71%) Build Cache 45 0 8.5GB 8.5GB (100%)

Build Cacheの「RECLAIMABLE」の値が大きい場合、不要なDockerキャッシュが溜まっているサインです。上記の例では、ビルドキャッシュだけで8.5GBを占有しており、全て回収可能な状態です。

より詳細な内訳を確認したい場合は、-vオプションを付けて実行します。

docker system df -v

Dockerのビルドキャッシュを削除するコマンド一覧

Dockerには、不要なリソースを削除するためのpruneコマンドが用意されています。目的に応じて使い分けましょう。

ビルドキャッシュだけを削除する

docker builder prune

最も基本的なDockerキャッシュ削除コマンドです。現在使用中のキャッシュを残しつつ、不要なビルドキャッシュのみを削除します。確認プロンプトが表示されるので、内容を確認してから進めてください。

ビルドキャッシュを全て削除する

docker builder prune --all

--allオプションを付けると、使用中のキャッシュも含めて全て削除します。次回のビルドでキャッシュが効かなくなるため、ビルド時間が一時的に長くなる点には注意が必要です。本番環境で実行する際は、デプロイのタイミングを考慮しましょう。

確認なしで即座に削除する

docker builder prune --all --force

--force（-f）オプションで確認プロンプトをスキップできます。スクリプトやcronジョブでの自動実行時に使用します。

一定期間より古いキャッシュだけ削除する

docker builder prune --all --force --filter "until=72h"

--filter "until=72h"を指定することで、72時間以上前に作成されたDockerキャッシュのみを削除対象にできます。直近のキャッシュは残るため、ビルド速度への影響を最小限に抑えられます。

未使用リソースをまとめて削除する

docker system prune

ビルドキャッシュだけでなく、停止中のコンテナ、未使用のネットワーク、ダングリングイメージもまとめて削除します。ボリュームも含めて削除したい場合は--volumesオプションを追加します。

docker system prune --volumes

⚠ 注意: docker system pruneは影響範囲が広いため、まずはdocker system dfで状況を確認し、ビルドキャッシュが主な原因であればdocker builder pruneから始めるのが安全です。

コマンド比較表

コマンド削除対象安全性用途
docker builder prune未使用のビルドキャッシュ★★★日常的なキャッシュ削除
docker builder prune --all全ビルドキャッシュ★★☆ディスク逼迫時の対応
docker system pruneキャッシュ+コンテナ+イメージ+ネットワーク★☆☆包括的なクリーンアップ
docker system prune --volumes上記+ボリューム☆☆☆環境の完全リセット

Dockerキャッシュ削除の自動化：cronで定期実行する方法

手動でのDockerキャッシュ削除は即効性がありますが、放置すればまた同じ問題が再発します。cronジョブで定期的にpruneコマンドを自動実行するのが実用的です。

たとえば、毎週日曜の深夜3時に72時間以上前のキャッシュを削除する設定は以下の通りです。

# crontab -e で以下を追加 0 3 * * 0 docker builder prune --all --force --filter "until=72h" >> /var/log/docker-prune.log 2>&1

ログを残しておくことで、いつ・どのくらいのキャッシュが削除されたかを後から確認できます。

「どこまで残すか」のバランスは環境によって異なります。最初は長め（168h = 1週間）で設定し、様子を見ながら短くしていくのがよいでしょう。

CI/CDでのDockerキャッシュ管理のベストプラクティス

CI/CD環境では、ビルドの頻度が高いためDockerキャッシュの肥大化が特に顕著です。GitHub ActionsやGitLab CIを利用している場合、ビルド後のクリーンアップステップとしてpruneコマンドを組み込むことを検討してみてください。

一方で、CI/CDではビルド速度も重要な指標です。キャッシュを毎回全て削除してしまうとビルド時間が倍以上になることもあります。私たちも当初はビルドのたびに全キャッシュを削除していたのですが、ビルド時間が大幅に伸びてしまい、方針を見直した経験があります。

現在は、以下の運用に落ち着いています。

  • ビルドごとの削除ではなく、日次の定期クリーンアップを実施
  • --filterによる期間指定で、直近のキャッシュは保持
  • Docker BuildKitの外部キャッシュストレージ機能で、キャッシュをオブジェクトストレージに退避

特にBuildKitの外部キャッシュは、ローカルディスクの圧迫を根本的に解決しつつ、ビルド速度も維持できるため、本格的なCI/CD環境では導入をおすすめします。

Dockerfileの最適化でキャッシュ肥大化を根本から防ぐ

Dockerキャッシュの削除だけでなく、そもそもキャッシュが肥大化しにくいDockerfileを書くことも重要です。

マルチステージビルドの活用: 最終イメージに含まれるレイヤーを必要最小限に絞ることができ、キャッシュの生成量自体を抑えられます。

# ビルドステージ FROM node:20 AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # 実行ステージ（ビルド時のキャッシュは持ち込まない） FROM node:20-slim WORKDIR /app COPY --from=builder /app/dist ./dist COPY --from=builder /app/node_modules ./node_modules CMD ["node", "dist/main.js"]

.dockerignoreの設定: ビルドコンテキストに不要なファイルを含めないことで、無駄なキャッシュレイヤーの生成を防ぎます。

node_modules .git .next dist *.md

レイヤーの順序を意識する: 変更頻度の低いファイル（package.jsonなど）を先にCOPYし、変更頻度の高いソースコードを後にCOPYすることで、キャッシュヒット率を高められます。

まとめ：Dockerキャッシュ削除は「確認→削除→自動化」の3ステップ

Dockerのビルドキャッシュ肥大化は、多くの開発現場で起こりうる問題ですが、仕組みを理解すれば対処は難しくありません。

  1. 確認: docker system dfで現状を把握する
  2. 削除: docker builder pruneで不要なキャッシュを削除する
  3. 自動化: cronやCI/CDパイプラインに組み込み、再発を防ぐ

この3ステップを一度整えれば、Dockerキャッシュによるディスク容量不足に悩まされることは大幅に減るはずです。