Mac の Docker が容量を使いすぎるときの安全な減らし方

macOS で Docker が巨大に見える理由

Docker Desktop は、軽量な Linux 仮想マシンの中でコンテナを動かします。イメージ、コンテナの書き込み層、ビルドキャッシュ、ボリュームは、Finder で編集するような普通のフォルダではなく、大きなディスクイメージファイルの中に保存されます。Docker Desktop のバージョンや設定によって異なりますが、このファイルの名前は一般に Docker.raw です。

ディスクイメージの最大容量、Finder に表示される見かけのサイズ、Docker が現在使っている容量は、同じ数字になるとは限りません。スパースファイルは大きな論理サイズを持ちながら、ホスト上では実際にはそれより少ない容量しか使わないことがあります。Finder で見えるいちばん大きな数字がそのまま空くと考えず、Docker 自身の集計と macOS の空き容量から確認を始めてください。

Docker.raw を削除すると、Docker のオブジェクト管理を迂回して、ローカルのイメージ、コンテナ、ボリュームがまとめて失われるおそれがあります。Finder で移動すると Docker Desktop が動かなくなることもあります。Docker の Mac 向けドキュメントも、ディスクイメージの場所は Settings から変更するよう案内しています。

読み取り専用で容量を確認する

Docker Desktop を起動してターミナルを開き、docker system df を実行します。イメージ、コンテナ、ローカルボリューム、ビルドキャッシュの使用量と、Docker が回収可能と判断した容量（RECLAIMABLE）がまとめて表示されます。詳細を見るには docker system df -v を使います。

RECLAIMABLE の数字は慎重に読んでください。イメージは複数のコンテナで共有されていることがあり、タグを 1 つ消しても表示された容量がすべて戻るとは限りません。また、いまはどのコンテナにも接続されていないため未使用に見えるボリュームにも、後で復元するつもりのデータベースが入っていることがあります。

Docker Desktop の Settings > Resources も開き、お使いのバージョンにあるディスク使用量の上限とディスクイメージの場所を確認します。変更する前に、現在の値を記録してください。Docker が起動しない場合は、リセットや再インストールを試す前に、Docker の公式の復旧手順でデータファイルをバックアップしてください。

1. docker system df -v を実行し、結果を日付付きで保存します。
2. docker ps -a でコンテナを一覧にし、本当に不要になった停止中のものを見極めます。
3. docker image ls でイメージを一覧にし、重要なタグがどのプロジェクトや CI ワークフローで使われているかを対応付けます。
4. docker volume ls でボリュームを一覧にし、データを持つボリュームごとに持ち主とバックアップの有無を確認します。
5. 最後に、docker builder du か、現在使っているビルダーが対応するコマンドでビルドキャッシュを調べます。

実行中のコンテナに接続されていないからといって、そのボリュームのデータが不要とは限りません。Compose のプロジェクト、停止中のデータベース、一時的な復旧作業などでは、正当なボリュームが接続されないまま残っていることがよくあります。

停止コンテナと未使用イメージを個別に削除する

不要と確認できた停止中のコンテナは、docker container rm にコンテナ名または ID を付けて削除します。停止中のコンテナを削除すると書き込み層の変更は失われますが、ボリュームの削除を明示的に指定しない限り、名前付きボリュームは残ります。

使っていないと分かっているイメージは、docker image rm にタグまたは ID を付けて削除します。まだコンテナから参照されていると表示された場合は、強制削除せずに、そのコンテナを確認してください。頻繁に再ビルドしていてネットワークが遅いなら、取得に時間のかかるベースイメージをいくつか残しておくのも合理的です。

カテゴリを絞ったコマンドのほうが、システム全体の prune より影響範囲が小さく済みます。docker container prune は、確認の後に停止中のコンテナをすべて削除します。docker image prune は既定では dangling イメージを削除し、-a を付けるとどのコンテナからも参照されていないイメージまで対象が広がります。実行のたびに、確認時の表示内容を読んでください。

ボリュームに触れずにビルドキャッシュを整理する

BuildKit は、変更のないビルド手順を再利用できるようにレイヤーを保持します。活発に開発している Mac では、ビルドキャッシュが回収可能な容量のうち最大のカテゴリになることがありますが、Dockerfile とビルドコンテキストがあれば、すべて作り直せます。

既定のビルダーの使われていないビルドキャッシュは docker builder prune で削除します。buildx で管理しているビルダーには docker buildx prune を使い、お使いの Docker のバージョンで使えるオプションを確認してください。どちらも強制フラグを付けない限り確認を求めます。この確認は安全のためのチェックとして残しておきましょう。

次のイメージのビルドは遅くなり、レイヤーの再ダウンロードや再ビルドが発生します。これが毎週のように起きるなら、無条件の定期削除を組むより、Dockerfile とキャッシュの方針を見直してください。頻繁に変わるソースのコピーより前に依存関係のインストールを置き、.dockerignore を絞り込み、常設の CI 用ビルダーにはキャッシュの上限を明示します。

docker system prune の範囲を理解する

docker system prune は、複数の削除をまとめた便利なコマンドです。Docker のドキュメントによると、既定では停止中のコンテナ、使われていないネットワーク、dangling イメージ、使われていないビルドキャッシュを削除します。これらのカテゴリを確認した後であれば、使ってよい場面もあります。

既定のコマンドはボリュームを削除しません。--volumes を付けると匿名ボリュームまで対象が広がり、その中には実際のアプリのデータが入っていることがあります。安易に付けないでください。また、お使いの Docker のバージョンで何が削除されるかを確かめずに、フォーラムで見かけた 1 行の掃除コマンドをそのまま実行しないでください。

-a を付けると、イメージの削除対象が dangling イメージから、コンテナで使われていないすべてのイメージへ広がります。データは失われなくても、大量の再ダウンロードと再ビルドが必要になることがあります。容量の大きい原因が分かっているなら、イメージを個別に削除するほうを選んでください。

1. 読み取り専用の確認を済ませ、データが重要なボリュームはバックアップします。
2. 原因が 1 つのカテゴリで説明できるなら、ビルドキャッシュや停止中のコンテナを個別に削除します。
3. -a も --volumes も付けない docker system prune は、確認時に表示されるすべてのカテゴリを削除してよい場合だけ実行します。
4. docker system df -v をもう一度実行し、重要なプロジェクトが起動することを確かめます。
5. Docker Desktop がホスト側の容量を返すのを待ってから、macOS の空き容量を確認します。

ボリュームとデータベースを守る

ボリュームは、コンテナより長く残るように設計されています。PostgreSQL、MySQL などの開発用サービスのボリュームには、関連するコンテナが停止または削除された後も、そのデータの唯一のローカルコピーが入っていることがあります。持ち主とバックアップが分かるまでは、キャッシュではなく、大切な書類と同じように扱ってください。

Docker のバックアップに関する案内にあるとおり、ボリュームのデータは別にバックアップする必要があります。できるだけデータベース自身のエクスポート機能を使うか、復元を試したことのあるボリュームのバックアップ手順を使います。稼働中のデータベースのボリュームからディレクトリをコピーしても、整合性のとれたバックアップになるとは限りません。

Compose ファイルではボリュームに名前を付け、持ち主がすぐ分かるようにします。どのプロジェクトが作ったか、どう復元するか、いつ不要になるかを記録しておけば、次の整理は当て推量ではなく、保持するかどうかの判断になります。

Docker Desktop のストレージを縮小・移動・リセットする

オブジェクトを整理してもホスト側の容量不足が解消しない場合は、Docker Desktop の Settings でディスクイメージを管理します。使える設定はバージョンによって異なりますが、ディスク使用量の上限やディスクイメージの場所を変更するなら、公式にサポートされたこの画面から行ってください。

Docker.raw を Finder で別のドライブにドラッグしないでください。Docker も、ディスクイメージの移動は Settings から行うよう明確に注意しています。初期状態へのリセット（Reset to factory defaults）、アンインストール、データが失われるディスクサイズの変更を行う前に、必要なイメージを書き出すか再取得できることを確かめ、ボリュームを別にバックアップし、必要な設定を保存してください。

ディスクイメージの形式や Docker Desktop の動作によっては、オブジェクトを削除してからホスト側の容量が戻るまで時間がかかることがあります。Docker の Mac 向け FAQ によると、Docker.raw は旧形式の qcow2 よりずっと早く容量を返します。すぐにさらに削除するのではなく、prune が終わった後でもう一度測ってください。

AskClean がすること、しないこと

AskClean は Docker Desktop のランチャーのキャッシュを表示し、Docker が管理するストレージがホストのどこで容量を使っているかを示します。Docker.raw、Docker のグループコンテナのデータ、認証情報、イメージ、ボリュームは、普通のアプリのキャッシュのように削除するのではなく、Docker が管理するもの、または選択対象にしないものとして意図的に区別します。

コンテナのオブジェクトと仮想ディスクには、Docker 自身の CLI と Settings を使ってください。AskClean の役割は、Mac 側の見えにくい占有を見えるようにし、広範な整理が認証情報やボリュームのデータにまで及ばないようにすることです。安全な流れは変わりません。AskClean で場所を確かめ、docker system df -v で診断し、該当する Docker のカテゴリだけを prune します。

Docker のカテゴリ別の削除リスク

Docker の仮想ディスクには、作り直せるレイヤーと、残すべきデータの両方が入っています。

よくある質問