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つです。
| オプション | 役割 | 使用例 |
|---|---|---|
-d, --detach | バックグラウンドで起動する | docker compose up -d |
--build | 起動前にイメージを再ビルドする | docker compose up --build |
--force-recreate | 変更がなくてもコンテナを再作成する | docker compose up --force-recreate |
--no-deps | 依存サービスを起動せず対象サービスだけ動かす | docker compose up --no-deps web |
--remove-orphans | Composeファイルにない古いコンテナを削除する | docker compose up --remove-orphans |
それぞれの詳しい挙動と使い分けは、次の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でよく使う主要オプション
ここでは、実務で使う頻度が高いオプションを一つずつ確認します。それぞれ「結論」→「使い方」→「使う場面」の順で説明します。
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 build | イメージをビルドする | する | しない |
docker compose up | コンテナを作成・起動する | 既存イメージがなければする | する |
docker compose up --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
どちらの手順を選ぶかは、「ビルドと起動を同時に確認したいか」「ビルドの完了と起動のタイミングを分けたいか」で判断すると迷いません。
TVCMで話題の【ココナラ】無料会員登録はこちら
docker compose up オプションのよくある質問
-
docker compose up -dの-dにはどんな意味がある？
-
-detachの短縮形で、コンテナをバックグラウンドで起動する指定です。付けない場合、docker compose upはログを表示し続けるフォアグラウンド動作になり、Ctrl+Cで停止するまでターミナルを専有します。常駐させたいサービスではdを付けるのが基本です。
-
docker compose up –buildはいつ使う？
-
Dockerfileやビルドコンテキストの内容を変更し、その変更をコンテナに反映してから起動したいときに使います。
docker compose upは既存イメージがあればそれをそのまま使うため、コードを直した直後は--buildを付けないと古い内容のまま起動してしまいます。
-
-force-recreateと–buildの違いは？
-
-buildはイメージの再ビルドを行うオプション、-force-recreateはコンテナの再作成を強制するオプションです。目的が異なるため、状況によっては両方同時に指定します。docker compose up --build --force-recreateイメージだけ新しくしても既存コンテナがそのまま使われて反映されない場合や、逆にコンテナだけ作り直してもイメージが古いままの場合があるため、確実に両方やり直したいときはこの組み合わせが有効です。
-
特定のサービスだけ起動するには？
-
コマンドの末尾にサービス名を指定します。
docker compose up web依存関係にある他のサービスまで起動したくない場合は、
--no-depsを組み合わせます。docker compose up --no-deps web
まとめ
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を目的に応じて組み立てやすくなります。
