docker compose stopとdownの違いは？

短い答え

docker compose stop はコンテナを停止し、ディスク上に残します。docker compose down はコンテナを停止した後、コンテナとプロジェクト用に Compose が作成したネットワークを削除します。どちらのコマンドも named volume には影響しません。データベースが削除されるのは -v を追加した場合だけです。たとえば docker compose down -v のように指定すると、Compose ファイルの volumes セクションで宣言された named volume が削除されます。

違いは以上です。このガイドの残りでは、Postgres の volume が down 後も残り、down -v で削除されることを確認します。また、--force-recreate が必要になる2つのケースについて説明します。

docker compose stop: コンテナが残る場合

stop は各コンテナのメインプロセスに SIGTERM を送信して待機し、プロセスがまだ実行中であれば SIGKILL を送信します。デフォルトの待機時間は 10 秒で、-t で変更できます。何も削除されません。コンテナの ID、書き込み可能レイヤー、IP の予約、ログは維持されます。

docker compose stop
docker compose ps -a

docker compose ps を単独で実行すると、実行中のコンテナだけが表示されます。そのため、stop の後に空のテーブルが表示され、コンテナが削除されたと考えてしまうことがあります。ps -a は停止済みのコンテナも含めて表示します。各サービスの横に Exited (0) が表示されることを確認できます。docker compose start で再起動すると、まったく同じコンテナが再利用されます。

コンテナはまだ存在するため、volume の外部にコンテナ内で書き込んだ内容は残っています。docker compose exec で手動インストールしたパッケージや、コンテナ内で編集した設定ファイルも含まれます。デバッグ中に stop を優先する実務上の理由はここにあります。同じ状態で再起動できるためです。

docker compose down: コンテナとネットワークを削除します

down はコンテナを停止してから、コンテナと、Compose がプロジェクト用に作成したデフォルトネットワークを削除します。Docker のドキュメントでは、up が作成したコンテナ、ネットワーク、ボリューム、イメージを停止・削除するコマンドと説明されています。ただし、ボリュームとイメージが対象になるのは、-v と --rmi を指定した場合だけです。

docker compose down
docker compose ps -a
docker network ls

down の実行後、ps -a はプロジェクトについて何も出力せず、<project>_default ネットワークも削除されます。プロジェクト名は、Compose ファイルで name: を設定するか、-p を指定しない限り、ディレクトリ名から決まります。コンテナの書き込み可能レイヤー内で行った変更はすべて復元できなくなります。そのため、down はコンテナを破棄し、ボリュームに保存したデータは保持するコマンドとして扱ってください。

誤ったディレクトリで実行すると、no configuration file provided: not found になります。Compose は対象のプロジェクトを特定できないため、処理を拒否します。プロジェクトのディレクトリにいない場合は、docker compose -f /srv/myapp/compose.yaml down を使用してください。

docker compose down はボリュームを削除しますか？

いいえ。トップレベルの volumes キーで宣言した名前付きボリュームは、down より長く存続し、接続されていたコンテナが削除された後も残ります。これは、このコマンドで最もよくある懸念事項です。Compose v2 でも動作は変わりません。

検証できるスタックを用意します。空のディレクトリ voltest を作成し、その中の compose.yaml に次の内容を保存します。

services:
  db:
    image: postgres:16.4
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

スタックを起動し、後で識別できる行を書き込みます。

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "create table marker (note text);"
docker compose exec -T db psql -U postgres -c "insert into marker values ('survived');"

次にコンテナを削除し、ボリュームを確認します。

docker compose down
docker volume ls

出力には voltest_pgdata が残っています。コンテナは削除されましたが、データは残っています。スタックを再起動し、その行を読み取ります。

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "select * from marker;"

survived を含む行が 1 行表示されます。新しいコンテナは異なる ID を持つ別のコンテナですが、同じボリュームに接続されています。全体像については、Compose の基本ガイドで、名前付きボリュームと bind mount の違い、およびそれぞれがホスト上のどこに実体を持つかを確認できます。

down -v が削除するもの

-v（長形式は --volumes）は、Compose ファイルの volumes セクションで宣言された名前付きボリュームと、コンテナに接続された匿名ボリュームを削除します。同じスタックに対して実行してください。

docker compose down -v
docker volume ls

voltest_pgdata は一覧に表示されなくなります。スタックを再起動すると、Postgres のエントリポイントは空のデータディレクトリを検出し、新しいクラスタを初期化します。コンテナログにも、そのことが明記されます。

The files belonging to this database system will be owned by user "postgres".
PostgreSQL init process complete; ready for start up.

数か月間稼働していたスタックでこのブロックが表示された場合、ボリュームが削除されたことを意味します。marker テーブルは失われ、復旧する方法はバックアップだけです。

-v で削除されないストレージもあります。bind mount はホスト上のパスなので、Docker はマウントを解除するだけで、ファイルはその場所に残ります。external: true が付いたボリュームは、このプロジェクト外の構成要素に属するものとして宣言されているため、Compose は削除しません。down -v を実行する前に Compose ファイルから名前付きボリュームを削除すると、そのボリュームは宣言されていないため、Compose は削除対象として認識できず、docker volume prune の孤立リソースとして残ります。

最後のケースは、リファクタリング時に問題になりやすいものです。ファイルからサービスとそのボリュームを削除してから down -v を実行すると、ファイルに記載がなくなっているため、ボリュームは残ります。ファイルを編集する前に down -v を実行してください。

実際に --force-recreate が必要になる場合

docker compose up -dは毎回すべてを再構築するわけではありません。Compose は各サービスの解決済み設定のハッシュを、ラベルとしてコンテナに保存します。ハッシュとイメージ ID が一致している場合、コンテナはそのまま維持され、Recreatedではなく Container voltest-db-1 Runningになります。この動作はほとんどの場合に望ましいものです。up -dを繰り返し安全に実行できるためです。

一部の編集が何も変更しないように見える理由も、これで説明できます。Compose がハッシュ化するのは、定義が参照するファイルの内容ではなく、解決済みのサービス定義です。コンテナにマウントされ、起動時に一度だけ読み込まれる設定ファイルを編集しても、マウントパスは変わらないため、コンテナは再作成されません。サービスは起動時に読み込んだ値のまま実行を続けます。

docker compose up -d --force-recreate

各コンテナを停止して削除し、同じ定義から新しいコンテナを作成します。マウントした設定ファイルを編集した後や、コンテナの状態が説明できない状態になった場合に使用します。ボリュームは変更されないため、force recreate を実行してもデータベースは保持されます。同じタグでより新しいイメージを使用するには、pull も必要です。

docker compose pull
docker compose up -d

pullは新しいイメージ ID を取得し、up -dは実行中のコンテナと異なるイメージ ID を検出して、自動的にコンテナを再作成します。pullなしで --force-recreateを追加すると、同じ古いイメージから新しいコンテナが作成されます。そのため、「force recreate を実行したのに、まだ古いバージョンのままだ」という問題がよく起こります。

docker compose restartはこれらの処理を行いません。既存のコンテナを再起動するだけで、Compose ファイルを再読み込みしません。そのため、変更した環境変数やポートマッピングは適用されません。ファイルを編集した場合は、up -dを使用します。

維持すべきメンタルモデル

コンテナは置き換え可能です。コンテナはプロセスと薄い書き込み可能レイヤーで構成され、Compose はファイルから同一のコンテナを約 1 秒で作成できます。一方、ボリュームは置き換えできません。リポジトリ内のどのファイルからも再生成できない状態の唯一のコピーを保持しているためです。

Compose の各コマンドは、この分離に対応しています。stop と start はコンテナを維持します。down と up はコンテナを置き換え、ボリュームを維持します。down -v は状態を削除する唯一の通常コマンドです。そのため、明示的なフラグが必要です。実際の環境で実行する前に、少なくとも 1 回リストアを実行したバックアップがあることを確認してください。

同じ考え方は Secret にも当てはまります。POSTGRES_PASSWORD で設定したパスワードは、データベースの初期化時に 1 回だけ読み込まれます。そのため、環境ファイル内でパスワードを変更して up -d を実行しても、password authentication failed for user "postgres" になります。コンテナは新しくなりますが、ボリュームは古いままです。古いボリュームには、依然として古いパスワードが保存されています。Compose が env ファイルと Secret を解決する方法では、同じ変数が 2 回設定された場合にどのレイヤーが優先されるかを説明しています。

エラーのパターンと表示されるメッセージ

no configuration file provided: not foundは、Composeをcompose.yamlもdocker-compose.ymlもないディレクトリで実行していることを示します。完全なパスを指定して-fを渡してください。

downでnetwork voltest_default has active endpointsが表示される場合、このプロジェクト外のコンテナがプロジェクトネットワークに接続されています。通常は、docker run --networkで手動起動したコンテナです。そのコンテナを削除してから、downを再度実行してください。

Found orphan containers ([voltest-old-1]) for this projectは、サービスの名前を変更または削除した後に表示されます。古いコンテナには、プロジェクトのラベルが残っています。docker compose down --remove-orphansでそれらを削除できます。正常なスタックに対して実行しても問題ありません。

手動でdocker volume rmを実行してError response from daemon: remove voltest_pgdata: volume is in useが表示される場合、停止中のコンテナを含め、いずれかのコンテナがそのボリュームを参照しています。先にdocker compose downを実行してからボリュームを削除するか、down -vを使用してください。より大規模なプロジェクトでは、複数サービスのComposeスタックを確認すると、1つのプロジェクトで蓄積するボリューム数が分かります。

FAQ

docker compose down を実行するとデータベースは削除されますか？

データベースが名前付きボリュームまたは bind mount に保存されている場合は削除されません。down はコンテナとプロジェクトのネットワークを削除しますが、ボリュームはデータを保持したままディスク上に残ります。次回の docker compose up -d では、新しいコンテナが同じボリュームに接続され、データを引き続き利用できます。名前付きボリュームを削除するのは docker compose down -v だけです。対象になるのは、Compose ファイルの volumes セクションで宣言されたボリュームだけです。

再び使いたいコンテナでは、stop と down にどのような違いがありますか？

stop はコンテナを保持するため、docker compose start を実行すると同じ書き込み可能レイヤーを持つ同じコンテナに戻ります。コンテナ内で手動でインストールまたは編集したものも残ります。down はコンテナを削除するため、次回の up -d ではイメージから新しいコンテナが作成され、手動で加えた変更は失われます。デバッグ中は stop を使用してください。

Compose プロジェクトが作成したものをすべて削除するにはどうすればよいですか？

docker compose down -v --rmi all --remove-orphans は、コンテナ、プロジェクトのネットワーク、ファイルで宣言された名前付きボリューム、サービスが使用したイメージ、プロジェクト名のラベルが付いたコンテナを削除します。bind mount や external: true と指定されたボリュームには影響しません。実行前に docker volume ls で削除対象を確認してください。

マウントした設定ファイルの変更がコンテナに反映されないのはなぜですか？

Compose は、解決後のサービス定義のハッシュを比較してコンテナを再作成するかどうかを判断します。このハッシュには、マウントしたファイルの内容は含まれません。パスが変わっていないため、Compose はコンテナを実行したままにし、起動時に読み込んだ値を使い続けます。docker compose up -d --force-recreate を実行して、ファイルを再度読み込む新しいコンテナを作成してください。

変更した新しい POSTGRES_PASSWORD が機能しないのはなぜですか？

Postgres イメージが POSTGRES_PASSWORD を読み込むのは、空のデータディレクトリを初期化するときだけです。ボリュームにはすでに初期化済みのクラスタが保存されているため、この変数は無視され、以前のパスワードが引き続き適用されます。password authentication failed for user "postgres" が表示されます。実行中のデータベース内で ALTER USER を使用してパスワードを変更するか、データが失われてもよい場合は docker compose down -v で最初からやり直してください。