本番サーバーで使う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 ではありません。既存の設定を使用して同じコンテナを停止および起動するだけです。そのため、変更した環境変数、新しいイメージタグ、編集したポートマッピングはまったく反映されません。ファイルの変更を適用するには、up -d を再度実行します。Compose は各サービスを実行中のコンテナと比較し、設定が変更されたサービスだけを再作成します。

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

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が実行中のコンテナと一致しないことを検出し、コンテナを再作成します。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 -a では Exited (1) と表示されているのに、ps にはコンテナが表示されない状態は、通常の起動失敗の状態です。終了コードを確認してから、ログを確認します。

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 が読み取れなくなります。

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

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

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

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

Composeはすべてのサービスを1つのプロジェクトネットワークに配置し、各サービス名をそのネットワーク上のDNS名にします。web内でgetent hosts dbを実行すると、名前解決に成功した場合はコンテナの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 は、コンテナとともにこれらの名前付きボリュームを削除します。テストスタックを完全に削除する場合には適切なコマンドですが、必要なデータを保持しているものには使用しないでください。確認も元に戻す操作もありません。バインドマウントはホストのファイルシステム上に存在するため、この操作の影響を受けません。この影響範囲の違いが、バインドマウントと名前付きボリュームを意図的に選択する理由の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 は、変数を展開して完全にマージしたファイルを出力します。これにより、変数が解決され、override ファイルが想定どおりに適用されたことを確認できます。未設定の変数は空の値として表示され、警告 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 はプロジェクト名を設定するため、同じスタックを2つ、別々のネットワークとボリューム名で並行して実行できます。再起動後にスタックを復元する処理は、手動で入力するコマンドではありません。自動的に実行する unit を設定します。詳細は、起動時にComposeスタックを開始する方法で説明しています。

FAQ

docker-compose をハイフン付きで記述する形式に置き換えたものは何ですか？

スペースで記述する docker compose です。これは 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 は実行中のプロセスに接続し、サービスの実際の状態を表示します。