Docker Compose実運用コマンド早見表

実際に使用する Compose コマンド

Docker Compose には 40 個を超えるサブコマンドがあります。サーバーで日常的に使うのは約 12 個です。このページでは、作業内容ごとにコマンドを分類し、それぞれの用途を簡潔に説明します。また、コマンドに潜む注意点については詳しい解説を案内します。

ここではすべて Compose V2 を使用します。つまり、スペースを含む docker compose であり、古い docker-compose スクリプトではありません。V2 は Docker Engine とともにインストールされる Go プラグインです。現在のパッケージでは V1 が廃止されているため、2026 年 7 月時点で新規の Ubuntu 環境に docker-compose: command not found が存在するのは、壊れているのではなく想定された状態です。docker compose version で確認してください。何も出力されない場合は、docker-compose-plugin パッケージをインストールしてください。

以下の各コマンドは、compose.yaml が置かれているディレクトリから実行します。Compose はそのディレクトリからプロジェクト名を取得し、そこを基準にファイルを検索するためです。1 つ上のディレクトリで同じコマンドを実行すると、Compose は no configuration file provided: not found で停止します。ファイル形式自体が初めての場合は、まず VPS で最初の Compose ファイルを作成する を読み、その後ここに戻ってコマンドを確認してください。

ライフサイクル: 入力する4つのコマンドと、コンテナを削除する1つのコマンド

docker compose up -d
docker compose up -d --wait
docker compose stop
docker compose start
docker compose restart web
docker compose down

up -d はネットワークとコンテナを作成し、コンテナを起動して終了します。コンテナが 作成された 時点ですぐに終了するため、続けて curl のプローブを実行するデプロイスクリプトは、初回に失敗することがあります。up -d --wait は、healthcheck を定義しているすべてのサービスが healthy を報告するまで待機し、いずれかが healthy にならない場合はゼロ以外の終了ステータスで終了します。このフラグの有効性は、背後にあるチェックの内容に左右されます。そのため、自動化で使用する前に、Compose が信頼できる healthcheck を作成してください。

stop はコンテナを停止しますが、コンテナ自体は保持します。そのため、start を実行すると、同じ書き込み可能レイヤーを持つ同じコンテナが再び起動します。down はコンテナを停止した後、コンテナとプロジェクトネットワークを削除します。コンテナ内で volume の外部に書き込まれたデータは、すべてコンテナとともに失われます。これは Compose で最も影響の大きい誤解です。down と stop の完全な違い では、この違いが問題になる箇所を説明しています。

restart は reload ではありません。既存の設定を使用して同じコンテナを停止・起動するだけなので、変更した環境変数、新しい image tag、編集した port mapping はまったく反映されません。ファイルの変更を適用するには、up -d を再度実行します。Compose は各サービスと実行中のコンテナを比較し、設定が変更されたサービスだけを再作成します。

変更を適用する: 再作成、pull、または rebuild

docker compose up -d --force-recreate
docker compose pull && docker compose up -d
docker compose build --no-cache web
docker compose up -d --build web

up -dは、変更がない場合は何も実行しません。そのため、繰り返し実行しても安全です。--force-recreateを指定すると、この比較を上書きし、設定が同一でもすべてのコンテナを置き換えます。コンテナ内に残った不整合な状態を解消する最も早い方法です。

イメージの更新に2つのコマンドが必要なのは、それぞれの役割が異なるためです。pullは、ファイルに記載された各タグの最新イメージをダウンロードします。続いて up -dが、サービスのイメージ ID と実行中のコンテナのイメージ ID が一致しないことを検出し、コンテナを再作成します。pull を省略すると、up -dはエラーを出さずに先月の latestを実行し続けます。

buildは、image:ではなく build:セクションを定義するサービスに適用します。up -d --buildはビルドと起動を1つの手順で実行します。コードを変更している間は、これが通常の手順です。キャッシュされたレイヤーが明らかに古い場合に限り --no-cacheを使用してください。すべてのレイヤーを最初から再ビルドするためです。

実行中の状態を確認する

docker compose ps
docker compose ps -a
docker compose logs -f --tail=100
docker compose logs --since 15m --timestamps db
docker compose top
docker compose ls

psは、実行中のコンテナだけを一覧表示します。起動中にクラッシュしたサービスは、-aを追加するまで表示されません。そのため、psにはコンテナが表示されない一方で、ps -aではExited (1)として表示される状態は、起動失敗時によくある状況です。終了コードを確認してから、ログを確認します。

logs -fはすべてのサービスを同時に追跡し、各行の先頭にサービス名を付けます。サービス間で通信し、イベントの順序が重要な場合に適した表示です。サービス名を指定すると対象を絞り込めます。1 か月間稼働しているコンテナでは、--tail=100が重要です。デフォルトでは履歴全体が表示され、ターミナルが大量の出力で埋まるためです。--since 15mを使うと、通常確認したい内容である、直前に実行した再起動中に起きたことを確認できます。

topは各コンテナ内のプロセスを一覧表示します。これにより、「コンテナが実行中」であることと、「コンテナ内のプロセスが実行中」であることを区別できます。lsを使うと現在のディレクトリの外に移動し、ホスト上のすべての Compose プロジェクトとその状態を一覧表示します。3 か月前に起動したスタックも見つけられます。

サービス内でシェルを起動する

docker compose exec web sh
docker compose exec -u root web sh
docker compose run --rm web env
docker compose run --rm --no-deps web sh

exec は、すでに起動しているコンテナ内でコマンドを実行します。run は同じサービス定義から新しいコンテナを起動します。サービスが exec を実行できる時間だけ稼働しない場合は、こちらを使用します。run には必ず --rm を組み合わせてください。これがないと、実行するたびに停止済みコンテナが残り、最終的に docker compose ps -a が読み取りにくくなります。

bash の前に sh を試してください。Alpine ベースのイメージには bash が含まれていないため、exec: "bash": executable file not found in $PATH というエラーになります。run に --no-deps を追加すると、サービスの依存関係を起動せずに済みます。これにより、簡単な設定確認のためにデータベース全体を起動する必要がなくなります。

run --rm web env は、すべての .env ファイル、environment: ブロック、シェル変数を統合した後に、サービスが実際に取得した環境を確認する最も速い方法です。値が誤っている場合は、通常、統合順序が原因です。Compose が env ファイルと Secret を解決する仕組みでは、どのソースが優先されるかを説明しています。

ネットワーク、ポート、名前解決

docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networks

Compose はすべてのサービスを 1 つのプロジェクトネットワークに接続し、各サービス名をそのネットワーク上の DNS 名として扱います。名前解決が機能している場合、getent hosts db を web 内で実行するとコンテナの IP アドレスが表示されます。機能していない場合は何も表示されません。そのため、「これらのコンテナは相互に通信できるか」を 2 秒で確認できます。名前解決はできるのに接続が拒否される場合、db 内のプロセスは 0.0.0.0 ではなく 127.0.0.1 にバインドされています。そのため、別のコンテナからのパケットを受け付けません。この仕組みの詳細は、Compose のネットワークとサービス DNS の仕組みで説明しています。

port web 80 を実行すると、コンテナのポートが公開されているホストのアドレスとポートが表示されます。マッピングが変数から設定されている場合でも、推測する必要がありません。ポートを公開すると、Docker が管理するファイアウォールルールも作成されます。このルールはユーザーが設定したルールより先に適用されるため、非公開だと考えていたサービスがインターネットからアクセス可能になることがあります。この事例については、Docker の公開ポートが ufw を迂回する理由で説明しています。

ボリュームとデータ

docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -v

config --volumes は、プロジェクトで宣言されている名前付きボリュームを 1 行に 1 つずつ表示します。この一覧がバックアップ対象です。cp は、シェルを開かずにコンテナとの間でファイルをコピーします。コンテナ側に指定する対象には、service:path の形式を使用します。

down -v は、コンテナとともにそれらの名前付きボリュームも削除します。テスト用スタックを削除する場合には適切なコマンドですが、必要なデータを保持している環境では使用しないでください。確認なしで実行され、元に戻せないためです。bind mount はホストのファイルシステム上に存在するため、この操作の影響を受けません。この影響範囲の違いが、bind mount と名前付きボリュームを意図的に使い分ける理由の 1 つです。

データを失わずにディスク領域を解放するクリーンアップ

docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune

--remove-orphansは、プロジェクトに属しているもののファイルに表示されなくなったコンテナを削除します。これは、サービス名を変更した場合に発生する状態です。これを実行しないと、それらのコンテナは実行を続け、docker compose psからは見えない状態になります。

docker system dfは、削除する前にディスク領域の使用状況を表示します。イメージ、コンテナ、ローカルボリューム、ビルドキャッシュを分けて表示し、それぞれについて解放可能な容量も示します。image prune -aは、どのタグからも参照されていないイメージをすべて削除します。大きなイメージを複数のバージョンで取得したサーバーでは、通常これが最も大きな効果を得られます。builder pruneはビルドキャッシュを削除します。独自のイメージをビルドするサーバーでは、ビルドキャッシュが気付かないうちに増加します。

これらの操作は、named volume には影響しません。named volume に影響するのは docker volume prune と docker compose down -v だけです。

問題が発生する前にファイルを検証する

docker compose config --quiet
docker compose config --services
docker compose --dry-run up -d

config --quiet は成功時に何も出力せずに検証するため、デプロイ前の処理や git hook に適しています。単純な config は、変数の展開と上書きファイルの適用が想定どおり行われたことを確認できる、統合・展開済みのファイル全体を出力します。未設定の変数は空の値として表示され、警告 The "X" variable is not set. Defaulting to a blank string. の隣に出力されます。

--dry-run はサブコマンドのフラグではなくグローバルフラグであるため、up の前に指定します。Compose が実行するすべての処理を出力しますが、実際には何も変更しません。重要なスタックで down を実行する前に、30 秒かけて確認する価値があります。

ファイル、プロファイル、プロジェクトをまたいだ運用

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d
docker compose -p staging up -d

複数の -f フラグは指定順に統合され、後のファイルがキー単位で前のファイルを上書きします。これは、1 つのベースファイルに小さな本番環境用の上書き設定を組み合わせる標準的な方法です。ただし、リストとマップではルールが異なるため、予期しない結果を調査する前に Compose が複数のファイルを統合する方法を確認してください。

--profile は、そのプロファイルが付いたサービスを、プロファイルが付いていないサービスとともに起動します。これにより、通常の up にデバッグ用ツールが含まれなくなります。-p はプロジェクト名を設定するため、1 つのスタックを 2 つ起動し、それぞれ別のネットワークとボリューム名で並行して実行できます。再起動後にスタックを復元する処理は、手動で入力するコマンドではありません。自動的に実行する unit として定義されており、起動時に Compose スタックを開始する方法で説明しています。

FAQ

ハイフン付きの docker-compose に取って代わったものは何ですか？

スペースで区切って docker compose と実行する Compose V2 です。これは Docker Engine に同梱されるプラグインで、V1 の Python ツールは現在のパッケージにはインストールされなくなりました。スペース形式を実行しても何も表示されない場合は、ディストリビューション用の docker-compose-plugin パッケージをインストールしてください。エイリアスを追加するのではなく、古いスクリプトをスペース形式に更新してください。V2 には V1 に存在しなかったフラグがあるためです。

docker compose restart で設定変更が反映されないのはなぜですか？

restart は既存のコンテナを、作成時の設定で停止・起動するだけで、compose.yaml を再読み込みしません。環境変数、ポート、ボリューム、イメージタグを変更した場合は docker compose up -d が必要です。これは各サービスと実行中のコンテナを比較し、差異があるコンテナを再作成します。ファイルの内容に変更がなくても置き換える場合は --force-recreate を追加してください。

サービスを新しいイメージに更新するにはどうすればよいですか？

docker compose pull を実行し、続けて docker compose up -d を実行してください。pull により、ファイル内の各タグに対応する最新のイメージが取得されます。up -d は、イメージ ID がコンテナと一致しなくなったサービスを再作成します。up -d だけを実行すると、すでにディスク上にあるイメージが再利用されます。そのため、latest に固定したスタックが、エラーを表示せず数か月前のビルドのまま動作することがあります。

稼働中のサーバーで安全に実行できるクリーンアップコマンドはどれですか？

docker system df、docker image prune -a、docker builder prune はイメージとキャッシュだけを削除するため、稼働中のサービスは動作し続け、名前付きボリュームも変更されません。危険なのは docker compose down -v と docker volume prune の組み合わせです。これらは確認なしで名前付きボリュームを削除します。最初に docker compose config --volumes を実行し、何が削除対象になるかを確認してください。

スタック全体を起動せずに、1 つのコマンドを実行できますか？

はい。docker compose run --rm --no-deps web sh は web のサービス定義から単一のコンテナを起動し、依存関係を無視して、終了時にコンテナを削除します。コンテナがすでに実行中の場合は exec を使用してください。exec は実行中のプロセスに接続し、サービスの実際の状態を表示するためです。