docker compose up オプションの使い方｜-d・–buildなど

docker compose up オプションには、バックグラウンド起動やイメージの再ビルド、コンテナの再作成など、Docker Composeを効率よく使うためのさまざまな指定があります。ただ、-dや--build、--force-recreateなど似たようなオプションが多く、「どれを使えばよいのか」「複数のオプションをどう組み合わせればよいのか」と迷うこともあります。

この記事では、docker compose upでよく使うオプションを、基本的な使い方から目的別の活用方法まで整理します。コンテナが起動したまま処理が終わらない場合の確認方法や、docker compose buildとの違いもあわせて紹介します。

docker compose up オプションの基本

docker compose upは、Composeファイルに定義したサービスのコンテナを作成し、起動するコマンドです。イメージがなければビルドし、コンテナが存在しなければ作成し、すでにあるコンテナは設定変更を検知して再作成します。実行すると、各コンテナのログがまとめてターミナルに表示され続けます。

まずは基本の構文と、押さえておきたいオプションの全体像を確認しましょう。

docker compose upの構文と基本的な使い方

基本構文は次の通りです。

docker compose up [OPTIONS] [SERVICE...]

• OPTIONS：起動方法を制御する指定（d、-build など）
• SERVICE：起動対象を絞り込むサービス名（Composeファイルの services: 配下に書いた名前）

何も指定せずに実行すると、Composeファイルに定義された全サービスが起動します。

docker compose up

この状態はフォアグラウンドで動作し続け、Ctrl+Cで停止するまでログが流れ続けます。バックグラウンドで動かしたい場合は後述の -d を使います。

まず覚えたい主要オプション一覧

最初から全オプションを覚える必要はありません。実務でよく使うのは次の5つです。

それぞれの詳しい挙動と使い分けは、次のH2セクションでオプションごとに解説します。

オプションとサービス名指定の違い

docker compose up の後ろに置く文字列は、「オプション」か「サービス名」のどちらかです。書き方は似ていますが役割はまったく異なります。

• オプションは または - から始まり、起動の挙動そのものを変える指定です。
• サービス名はComposeファイルに書いたサービスの識別子で、起動対象を絞り込む指定です。

例えば、次のComposeファイルがあるとします。

services:
  web:
    build: .
  db:
    image: postgres

このとき、以下のように書くと意味が変わります。

docker compose up -d

→ オプション -d のみを指定。web と db の両方をバックグラウンドで起動します。

docker compose up -d web

→ オプション -d に加えて、サービス名 web を指定。web だけをバックグラウンドで起動します（web が依存していれば db も一緒に起動します)。

このように、オプションとサービス名は同じコマンドの中で組み合わせて使えます。特定のサービスだけを対象にする方法は、後の「docker compose upを目的別に使い分ける方法」で具体例とあわせて解説します。

docker compose up

docs.docker.com

docker compose upでよく使う主要オプション

ここでは、実務で使う頻度が高いオプションを一つずつ確認します。それぞれ「結論」→「使い方」→「使う場面」の順で説明します。

d（–detach）でバックグラウンド起動する

結論：ターミナルを占有せずにコンテナを動かし続けたいときに使います。

docker compose up -d

docker compose up を素のまま実行すると、コンテナのログを表示し続けるフォアグラウンド動作になり、Ctrl+Cで停止するまでターミナルが専有されます。-d（ロングオプションは --detach）を付けると、コンテナをバックグラウンドで起動し、コマンドはすぐに終了してターミナルの操作を続けられます。

起動後の状態確認には次のコマンドを使います。

docker compose ps

注意点： -d は --abort-on-container-exit と同時に使えません。片方がコンテナの停止をトリガーに全体を止める仕組みのため、バックグラウンド動作と両立しないためです。

-buildでイメージを再ビルドして起動する

結論：Dockerfileやビルドコンテキストを変更した内容を反映してから起動したいときに使います。

docker compose up --build

docker compose up は、既存のイメージをそのまま使ってコンテナを起動します。Dockerfileを書き換えても、--build を付けなければ古いイメージのまま起動してしまいます。コードを変更した直後や、依存パッケージを追加した直後は --build を付けて起動するのが確実です。

docker compose up -d --build

このように -d と組み合わせれば、再ビルドしてからバックグラウンドで起動できます。docker compose build との役割の違いは、後述の「docker compose upとdocker compose buildの違い」で詳しく比較します。

-force-recreateと–no-recreateを使い分ける

結論：設定やイメージに変更がなくてもコンテナを作り直したいなら --force-recreate、逆に既存コンテナをそのまま使いたいなら --no-recreate を使います。

docker compose up は本来、サービスの設定やイメージに変更があった場合だけコンテナを再作成する仕組みです。この2つのオプションは、その自動判定を上書きします。

docker compose up --force-recreate

設定ファイルの変更を検知できないケースや、コンテナ内の状態をリセットして一から起動し直したいときに使います。環境変数の注入タイミングがずれている、コンテナ内にゴミが残っている、といった原因不明の不具合を切り分けたいときにも有効です。

docker compose up --no-recreate

すでに起動しているコンテナに手を加えたくない場合や、起動済みコンテナへの影響を避けながら停止中のコンテナだけ起動したい場合に使います。

注意点： --force-recreate と --no-recreate は同時に指定できません。目的が正反対のため、Compose側でエラーになります。

-no-depsで依存サービスを起動せずに実行する

結論：依存関係にあるサービスまで巻き込みたくないときに使います。

例えば、web サービスが db サービスに依存しているComposeファイルがあるとします。通常は web を起動すると db も一緒に起動しますが、--no-deps を付けると web だけが対象になります。

docker compose up --no-deps web

すでに db が起動している状態で web だけ再起動したい場合や、依存サービスに影響を与えたくない検証作業のときに使います。db がまだ一度も起動していない場合、--no-deps を付けると web はコンテナを起動できても、接続先の db が存在せず動作しないことがある点には注意してください。

-remove-orphansで不要なコンテナを削除する

結論：Composeファイルから消したサービスの残骸（orphanコンテナ）を片付けたいときに使います。

orphanコンテナとは、過去に起動したものの、現在のComposeファイルにはもう定義が残っていないサービスのコンテナです。例えば以前は worker サービスがあったが、今は定義を削除した、というケースで発生します。

docker compose up --remove-orphans

サービス構成を整理した後や、docker compose ps で見覚えのないコンテナが残っているときに使うと、定義に存在しないコンテナだけをまとめて削除しながら起動できます。バックグラウンド起動と組み合わせる場合は次のようになります。

docker compose up -d --remove-orphans

docker compose upを目的別に使い分ける方法

オプションを一つずつ覚えるより、「何をしたいか」から逆引きできた方が実務では早いです。よくある目的別に、使うコマンドと理由をまとめます。

特定のサービスだけ起動する

目的：Webサービスだけ動かしたい、DBは触りたくない、といったケース。

Composeファイルの services: に定義したサービス名を、コマンドの末尾に指定します。

docker compose up web

web が他のサービスに依存していれば、それも一緒に起動します。依存サービスまで巻き込みたくない場合は、前のH2で説明した --no-deps を組み合わせます。

docker compose up --no-deps web

サービス名は空白区切りで複数指定できます。

docker compose up web worker

複数のComposeファイルを指定して起動する

目的：本番用と開発用でComposeファイルを分けて管理している場合に、両方の設定をまとめて反映したい。

Composeファイルの指定は -f（ロングオプションは --file）で行います。これは docker compose up 固有のオプションではなく、docker compose コマンド全体に対するオプションです。そのため up より前、compose の直後に置きます。

docker compose -f compose.yaml -f compose.dev.yaml up -d

• f を複数指定すると、指定した順番に設定がマージされます。後に指定したファイルの内容が、先に指定したファイルの同名項目を上書きする形です。開発環境向けの上書き設定（ポート変更やボリュームマウントの追加など）を compose.dev.yaml にまとめておき、本番用の compose.yaml に重ねる、という使い方が一般的です。
• f を省略した場合、Composeはカレントディレクトリとその親ディレクトリを遡って compose.yaml または docker-compose.yaml を自動的に探します。

dと–buildなど複数オプションを組み合わせる

目的：コードを変更した後、再ビルドしてからバックグラウンドで起動したい。

docker compose up -d --build

-build で最新のDockerfileの内容をイメージに反映し、d でバックグラウンドに回します。開発中に何度もコードを直しては起動し直す、という作業では最もよく使う組み合わせです。

サービスを絞りつつ再ビルドしたい場合は、サービス名も合わせて指定できます。

docker compose up -d --build web

不要な古いコンテナも一緒に片付けたいなら、--remove-orphans も加えられます。

docker compose up -d --build --remove-orphans

-abort-on-container-exitなどテスト時に使うオプション

目的：テスト用コンテナが処理を終えたら、関連する他のコンテナもまとめて停止したい。

CIでテストを実行する構成では、テストランナーのコンテナが処理を終えた（＝exitした）タイミングで、依存しているDBコンテナなども含めて全体を止めたいことがあります。そこで使うのが --abort-on-container-exit です。

docker compose up --abort-on-container-exit

いずれかのコンテナが停止すると、Composeは残りのコンテナもまとめて停止します。テストの終了コードをそのままコマンドの終了コードとして受け取りたい場合は、--exit-code-from にサービス名を指定します。

docker compose up --abort-on-container-exit --exit-code-from test

注意点： --abort-on-container-exit は -d と同時に使えません。「コンテナの停止を監視してコマンド自体を終了させる」仕組みのため、バックグラウンド起動とは前提が両立しません。CIのパイプラインなど、フォアグラウンドで結果を待ち受ける用途に向いたオプションです。

docker compose upが終わらないときの確認方法

「docker compose up を実行したら止まったように見える」という状態は、必ずしもエラーとは限りません。docker compose up は本来、コンテナのログを表示し続けながらフォアグラウンドで動作し続けるコマンドです。プロンプトが返ってこないのは、正常にログを流し続けているだけの可能性があります。

まずは「本当に起動が失敗しているのか」「単にフォアグラウンドで動き続けているだけなのか」を切り分けましょう。

docker compose psでコンテナの状態を確認する

結論：まずは別のターミナルからコンテナの状態を確認します。

docker compose up を実行したターミナルとは別に、もう一つターミナルを開いて次を実行します。

docker compose ps

STATUS が Up になっていれば、コンテナ自体は正常に起動しています。この場合、ターミナルが返ってこないのは想定通りの動作です。バックグラウンドで動かしたいなら、一度Ctrl+Cで停止してから -d を付けて起動し直します。

docker compose up -d

逆に STATUS が Restarting を繰り返している、あるいは Exited になっている場合は、コンテナ内のプロセスが起動直後に落ちています。次のログ確認に進んでください。

docker compose logsでエラーを確認する

結論：コンテナが起動に失敗している場合は、ログにエラーの原因が出ています。

docker compose logs

特定のサービスに絞り込みたい場合はサービス名を指定します。

docker compose logs web

出力をリアルタイムで追いたいときは --follow（短縮形 -f）を付けます。

docker compose logs -f web

ここで確認したいのは、アプリケーション側のエラー（設定ミス、接続先サービスへの疎通失敗、必須環境変数の未設定など）か、イメージやビルド自体の問題かの切り分けです。原因がアプリケーションコード側にある場合は、Composeのオプションではなく、コードやDockerfile、環境変数の設定を見直す必要があります。

-buildや–force-recreateで再作成する

結論：設定やDockerfileを直したのに反映されていない場合に使います。

ログを見て「修正したはずのコードが反映されていない」と分かったら、キャッシュされたイメージや古いコンテナ設定が残っている可能性があります。

docker compose up --build

Dockerfileやビルドコンテキストを変更した場合は、こちらで再ビルドしてから起動し直します。イメージ自体は変わっていないのにコンテナの状態がおかしい場合は、--force-recreate で作り直します。

docker compose up --force-recreate

両方組み合わせて、確実にビルドとコンテナ作成をやり直すことも可能です。

docker compose up --build --force-recreate

-remove-orphansで古いコンテナを整理する

結論：docker compose ps に見覚えのないコンテナが残っている場合は、これで整理します。

Composeファイルからサービス定義を削除した後も、そのサービスのコンテナが残り続けることがあります（orphanコンテナ）。これが原因でポートが競合し、新しいコンテナが正常に起動できないケースもあります。

docker compose up --remove-orphans

現在のComposeファイルに定義されていないコンテナを削除しながら起動するため、「昔作ったサービスの残骸が邪魔をしている」状況を解消できます。原因が分からず起動がうまくいかないときは、docker compose ps で余分なコンテナがないか確認する習慣をつけておくと、切り分けが早くなります。

docker compose upとdocker compose buildの違い

docker compose up と docker compose build は役割が異なります。混同しやすい部分なので、それぞれの範囲を明確にしておきます。

docker compose upは何をするコマンドか

docker compose up は、コンテナの作成と起動を担当するコマンドです。指定したサービスに対応するイメージがすでにあれば、それをそのまま使ってコンテナを起動します。イメージがまだ存在しない場合は自動的にビルドしますが、すでにイメージが存在する場合、Dockerfileの中身を書き換えただけでは再ビルドされません。

docker compose up

この挙動を知らずに「Dockerfileを直したのに反映されない」と困るケースは多いです。ビルドを強制したい場合は、後述の --build を付ける必要があります。

docker compose buildを使う場面

docker compose build は、コンテナを起動せず、イメージのビルドだけを行うコマンドです。

docker compose build

特定のサービスだけビルドしたい場合はサービス名を指定します。

docker compose build web

このコマンドが向いているのは、次のような場面です。

• CIパイプラインで、起動確認の前にビルドだけ先に済ませておきたい
• イメージをビルドしてレジストリにプッシュする準備をしたい（起動は不要）
• 複数サービスのうち、ビルドだけ時間のかかるサービスを先に済ませておきたい

コンテナを起動する必要がない作業では、up より build 単体の方が意図が明確です。

Dockerfileの変更を反映したいときのコマンド

Dockerfileやビルドコンテキスト内のファイルを変更した後、コンテナに反映してすぐ起動確認をしたい場合は、docker compose up --build を使うのが最も簡単です。

docker compose up --build

これは実質的に「docker compose build を実行してから docker compose up を実行する」のと同じ結果になりますが、コマンド1回で済みます。バックグラウンドで確認したい場合は組み合わせます。

docker compose up -d --build

一方、ビルドだけ先に終わらせておいて、起動は後のタイミングで行いたい場合は、build と up を分けて実行します。

docker compose build
docker compose up -d

どちらの手順を選ぶかは、「ビルドと起動を同時に確認したいか」「ビルドの完了と起動のタイミングを分けたいか」で判断すると迷いません。

docker compose up オプションのよくある質問

まとめ

docker compose upは、Composeファイルに定義したサービスのコンテナを作成・起動するためのコマンドです。オプションを使い分けることで、バックグラウンド起動やイメージの再ビルド、コンテナの再作成などを指定できます。

たとえば、Dockerfileの変更を反映しながらバックグラウンドで起動するなら、次のコマンドを使えます。

docker compose up -d --build

また、docker compose upを実行しても処理が終了しない場合は、必ずしもエラーとは限りません。フォアグラウンドでコンテナが動作している可能性があるため、docker compose psやdocker compose logsで状態やログを確認しましょう。

docker compose ps
docker compose logs

「イメージをビルドしたい」のか、「コンテナを起動したい」のかによって、docker compose buildとdocker compose upを使い分けることも重要です。Dockerfileの変更を反映してビルドから起動まで行う場合は、docker compose up --buildが使えます。

まずは-d、--build、--force-recreateなどの主要オプションを押さえ、必要になったときに--no-depsや--remove-orphansなどを使い分けると、docker compose upを目的に応じて組み立てやすくなります。

あわせて読みたい

【Docker攻略】docker buildでDockerfileを正しく指定する完全ガイド｜開発・本番別の使い分け

Docker buildで任意のDockerfileを指定する方法をわかりやすく解説。-fオプションの構文例や相対・絶対パスの注意点、開発・本番環境での使い分け、命名規則やdocker-composeとの連携まで、実務に役立つ運用テクニックをまとめました。Dockerfileの最適化と品質向上のヒントも満載です。

watashi.xyz

2025.08.05