Docker Composeは、Webサーバー・API・データベースのような複数のコンテナを1つのYAMLファイル(compose.yaml)に書き、docker compose upの1コマンドでまとめて起動・停止するツールです。この記事では、コンテナ同士をつなぐ仕組み、compose.yamlの主要キー、up・down・run・execの使い分け、本番への持ち込み方を、2026年11月15日時点の最新版v5.7.1を実際に動かした結果とあわせて解説します。
まとめ:Docker Composeの仕組みと書き方の要点(v5.7.1時点)
Docker Composeは、docker runを何本も手で打っていた構成をcompose.yamlに宣言し、同じ環境を誰でも1コマンドで再現できるようにする道具です。upを打つと、Composeはディレクトリ名から決まるプロジェクト名で<プロジェクト名>_defaultというネットワークを作り、全サービスをそこへつなぎます。サービス名がそのままホスト名になるため、アプリからDBへはdbのような名前で接続できます。
コマンドはスペース区切りのdocker composeを使います。ハイフン付きのdocker-compose(Python製のV1)は保守が終わっています。最新は2026年11月11日のv5.7.1で、ファイル名はcompose.yamlが推奨、先頭のversion:行は警告が出るだけなので省きます。
使いどころは、開発環境の再現、CIでの結合テスト、1台のサーバーで完結する小規模な本番までです。複数ホストへの分散、負荷に応じた自動スケール、無停止のローリング更新のどれかが要件に入ったら、Kubernetesなどのオーケストレーション基盤へ移します。
Docker Composeの仕組みとDocker単体との違い
Docker本体(Docker Engine)はコンテナを1つずつ作って動かす仕組みで、Composeはその上で複数コンテナの組み合わせを宣言として扱います。Docker本体の入れ方と必要スペックはDockerとは|仮想マシンとの違い・必要スペック・Desktop/Engineの違いとインストール手順【2026年10月】で扱っています。
docker runの手打ちとcompose.yamlの宣言の違い
Docker単体でWebとDBを動かすには、ネットワークをdocker network createで作り、必要ならボリュームをdocker volume createで事前作成し(未作成なら次のコマンドで自動作成)、docker run -d --name db --network app -e POSTGRES_PASSWORD=... -v db-data:/var/lib/postgresql postgres:18のような長いコマンドをコンテナの数だけ正しい順番で打つ必要があります。Composeでは、この手順をすべてcompose.yamlに書き、docker compose up -dだけで同じ状態を作ります。
手順がファイルになるので、Gitで差分を追え、新しく入ったメンバーも同じ構成を立ち上げられます。Composeが扱うのは「どのコンテナをどうつなぐか」で、イメージの中身はDockerfileが決めます。
| 道具 | 扱う範囲 | 主なコマンド |
|---|---|---|
| Dockerfile | 1つのイメージの中身 | docker build |
| Docker Engine | 1つのコンテナの実行 | docker run / exec |
| Docker Compose | 複数コンテナ・ネットワーク・ボリューム | docker compose up / down |
| Kubernetes | 複数ホストへの配置と自動復旧 | kubectl apply |
プロジェクト名・既定ネットワーク・サービス名による名前解決
Composeは、既定ではcompose.yamlのあるディレクトリ名をプロジェクト名に使い、生成するリソース名の接頭辞やラベルに反映します。プロジェクト名は-p、環境変数COMPOSE_PROJECT_NAME、トップレベルのnameで変えられます。公式のネットワークの解説は、docker compose upで<プロジェクト名>_defaultというネットワークが作られ、各サービスが内部DNSにサービス名で登録されると説明しています。
projというディレクトリでweb(nginx)とdb(PostgreSQL 18)を起動すると、ネットワークproj_default、ボリュームproj_db-data、コンテナproj-db-1・proj-web-1が作られ、webの中からdbの名前で届きました(2026年11月15日、colima上のDocker Engine 29.5.2とCompose v5.7.1で実行。以降の実行結果も同じ環境)。
$ docker compose up -d
Network proj_default Created
Container proj-db-1 Healthy
Container proj-web-1 Started
$ docker network ls --filter name=proj
NAME DRIVER
proj_default bridge
$ docker compose exec web getent hosts db
172.22.0.2 db db
同じcompose.yamlを1台で2組動かすときもプロジェクト名を変えれば、ネットワークもボリュームも別物として作られます。
docker-compose(V1)とdocker compose(V2以降)の違いと版番号が5へ飛んだ理由
ハイフン付きのdocker-composeはPythonで書かれた初代(V1)で、公式の廃止済みプロダクト一覧に「no longer maintained」として載っています。Docker社は2023年1月の告知でV1のサポートを2023年6月で終えると示しました。後継はGoで書き直されたDocker CLIのプラグインで、docker compose(スペース区切り)として呼びます。既存のdocker-compose.ymlもそのまま読めます。
後継の版番号は長く2.x系でしたが、2025年12月2日のv5.0.0で5へ移りました。リリースノートは、V1時代のファイル書式の版数「2.x」「3.x」と混同されないよう3と4を飛ばしたと説明しています。同じv5.0.0で、ビルドはDocker Bakeへ任せる形に変わっています。
その後もv5.3.0で後述のpre_startが入り、v5.7.0(11月2日)でサービス属性umaskが加わるなど、数週間おきに版が出ています。最新のv5.7.1(11月11日)は不具合修正の版です。
Docker Composeのインストールと版の確認
公式のインストール案内が推奨するのは、Engine・CLI・Composeを同梱したDocker Desktopを入れる方法です。Desktopの無料利用の条件(従業員250人未満かつ年間売上1,000万ドル未満など)はDocker Desktopのライセンスと導入手順|無料の条件・料金とWindows/Mac/Linuxへのインストールにまとめています。
Desktopを使わずLinuxサーバーにDocker Engineを入れている場合は、Linux向けのプラグイン導入手順に従い、Dockerの公式リポジトリからdocker-compose-pluginパッケージを入れます。更新も同じコマンドです。
# Ubuntu・Debian(Dockerの公式リポジトリを登録済みであること)
sudo apt-get update
sudo apt-get install docker-compose-plugin
# RHEL・Fedora などRPM系
sudo yum update
sudo yum install docker-compose-plugin
# 入ったか・どの版かを確かめる
docker compose version
# Docker Compose version v5.7.1
公式は単体バイナリ(standalone)の導入も残していますが「Legacy」の扱いで、呼び出しもdocker-composeになります。新しく入れるならDesktopかプラグインを選んでください。
compose.yamlの書き方:services・volumes・networksの主要キー
compose.yamlの書式はCompose Specificationに従います。トップレベルの要素はservices(コンテナ)、volumes(名前付きボリューム)、networks(独自のネットワーク)が中心です。
ファイル名の優先順位とversion行の扱い
公式のアプリケーションモデルの解説は、既定のファイル名をcompose.yaml(推奨)またはcompose.ymlとし、docker-compose.yaml・docker-compose.ymlも後方互換のために読むと定めています。両方を置いてdocker compose configを打つと、Found multiple config filesの警告のあとcompose.yamlが使われました。どちらが効いているか紛らわしいので、古い方は消しておきます。
先頭のversion: "3.8"のような行は、versionとnameのリファレンスによれば情報としてだけ残されており、Composeは常に最新のスキーマで検証します。v5.7.1ではthe attribute `version` is obsolete, it will be ignoredと警告が出るだけなので、新しく書くファイルでは省きます。
サービス定義の主要キー:image・build・ports・environment・command
各サービスには、既存のイメージを使うimageか、Dockerfileから作るbuildのどちらかを書きます。portsは「ホスト側:コンテナ側」の順でポートを公開し、environmentは環境変数、commandはイメージ既定の起動コマンドの上書きです。次はweb(Dockerfileで作る自作アプリ)・redis・db(PostgreSQL 18)の3サービスの例です。
services:
web:
build: .
command: npm start
ports:
- "8080:3000"
environment:
DATABASE_URL: postgres://app:secret@db:5432/app
REDIS_HOST: redis
depends_on:
db:
condition: service_healthy
restart: true
redis:
condition: service_started
redis:
image: redis:8-alpine
db:
image: postgres:18
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: secret
POSTGRES_DB: app
volumes:
- db-data:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
retries: 5
start_period: 30s
volumes:
db-data:
DATABASE_URLの接続先がdbになっているのは、前章のとおりサービス名がホスト名になるためです。$${POSTGRES_USER}の$$は、Composeにファイル読み込み時の変数展開をさせず、コンテナ内のシェルへ$のまま渡すための書き方です。パスワードを平文で置いているのは開発用の割り切りで、本番ではsecretsで渡します。build: .が参照するDockerfileの書き方はDockerfileとは|書き方・ファイル名(拡張子)・主要命令とsyntaxの版を実測で解説【2026年10月】を見てください。
サービス側のvolumesとトップレベルのvolumesの違い
compose.yamlにはvolumesが2か所に出てきます。サービスの中のvolumesは「どこをコンテナのどのパスにつなぐか」、トップレベルのvolumesは「Composeが管理する名前付きボリュームを作る」宣言です。上の例のdb-data:/var/lib/postgresqlは、トップレベルで宣言したdb-dataをコンテナの/var/lib/postgresqlへつないでいます。
| 書き方 | 種類 | 向く用途 |
|---|---|---|
| db-data:/var/lib/postgresql | 名前付きボリューム | DBのデータ |
| ./src:/app/src | バインドマウント | 開発中のソースコード |
| /tmp/cache(左辺なし) | 匿名ボリューム | 使い捨てのキャッシュ |
名前付きボリュームは<プロジェクト名>_db-dataの名前でDocker側に作られ、コンテナを作り直しても残ります。PostgreSQL 18の公式イメージはデータの置き場所が/var/lib/postgresql/dataから/var/lib/postgresql/18/dockerへ変わったため、古い記事の/var/lib/postgresql/dataをそのまま書くと起動に失敗します。詳細はDocker PostgreSQL構築の手順|18で変わったボリューム位置とcompose定義・initdb初期化を実装目線で解説で扱っています。
depends_onとhealthcheckによる起動順の制御
depends_onをサービス名の列挙だけで書く短い形では、Composeは依存先のコンテナが起動したところで次へ進み、中のDBが接続を受け付けるまでは待ちません。servicesリファレンスの長い形では、conditionに次の3つを指定できます。
service_started:起動したら進む(短い形と同じ)service_healthy:依存先のhealthcheckが通るまで待つservice_completed_successfully:依存先が正常終了するまで待つ(マイグレーション用の使い捨てサービス向け)
あわせてrestart: trueを書くと、Composeの操作で依存先を更新したときに依存元も再起動されます(コンテナが落ちて自動再起動した場合は対象外)。required: falseは、依存先が無くても警告だけで起動を続ける指定です。別途検証したnginxとPostgreSQLの2サービス構成(healthcheckのintervalは2s)をv5.7.1でup -dすると、dbがWaitingからHealthyになってからwebがStartedになり、全体で約7.5秒でした。
docker compose upから停止まで:主要コマンドの使い分け
日常で使うコマンドは次のとおりで、どれもcompose.yamlのあるディレクトリで打つか、-fでファイルを指定します。
| コマンド | 役割 |
|---|---|
docker compose up -d |
全サービスをバックグラウンドで起動 |
docker compose ps |
サービスの状態と公開ポート |
docker compose logs -f web |
webのログを追い続ける |
docker compose exec db psql -U app -d app |
動いているコンテナで実行 |
docker compose run --rm web |
新しいコンテナで1回だけ実行 |
docker compose build |
build指定のイメージを作り直す |
docker compose config |
重ね合わせ後の最終設定を表示 |
docker compose down |
コンテナとネットワークを削除 |
downとdown -vで消えるものの違い
downのリファレンスによれば、既定のdownが消すのはコンテナと、Composeファイルで定義したネットワークおよび使用中の既定ネットワークで、名前付きボリュームは残ります。-vを付けると、トップレベルで宣言した名前付きボリュームとコンテナに付いた匿名ボリュームも消えます。external指定のネットワークとボリュームは、どちらの場合も消えません。
dbに1行入れてから確かめると、次のようになりました。downのあとupし直しても入れた値(42)は読めましたが、down -vではボリュームproj_db-dataごと消えています。「DBを初期化したいとき」と「うっかり消してはいけないとき」の分かれ目は-vの有無だけなので、本番のサーバーでは-v付きのコマンドを履歴から再実行しないよう気を付けてください。
$ docker compose exec -T db psql -U app -d app -c "create table t(x int); insert into t values (42);"
$ docker compose down
$ docker volume ls --filter name=proj
local proj_db-data # 残っている
$ docker compose up -d
$ docker compose exec -T db psql -U app -d app -tAc "select x from t"
42
$ docker compose down -v
Volume proj_db-data Removed
runとexecの違い
execは、すでに動いているサービスのコンテナの中でコマンドを実行します。runは、そのサービスの設定で新しいコンテナを1つ作り、コマンドを1回だけ実行します。docker compose run --rm web sh -c 'hostname; getent hosts db'を打つと、proj-web-run-6d13924abfb5という別のコンテナが作られ、依存先のdbがHealthyになるのを待ってから実行されました。
runのリファレンスは、もう一つの差として、runはサービスに書いたportsを公開しないと述べています。動いているwebとポートがぶつからないための仕様で、公開したいときは--service-portsを付けます。使い分けは、DBへの接続確認やログの調査ならexec、マイグレーションやテストのように使い捨てで回す処理ならrun --rmです。
開発から本番へ:override・profiles・Watch・pre_startの使いどころ
開発環境を揃える用途では、リポジトリをgit cloneしてdocker compose upを打つだけで、Web・API・DB・キャッシュが揃います。フロントエンドを含む構成の例はNext.jsをDockerで動かす|Compose開発環境とstandalone本番イメージを16.4で実測、20近いサービスを1ファイルで束ねる規模の例はSupabaseセルフホストの構成と運用:Envoy移行後のDocker Compose実測で追えます。
compose.override.yamlと-fによる環境別設定の重ね合わせ
Composeは、compose.yamlと同じディレクトリにcompose.override.yamlがあれば、指定しなくても自動で重ねて読みます。environmentのA: baseを書いたcompose.yamlに、A: overrideだけを書いたcompose.override.yamlを置いてdocker compose configを打つと、最終設定はA: overrideになりました。開発用のバインドマウントやデバッグ用ポートはoverride側に寄せると、本番に持ち込まずに済みます。
本番用の差分は、公式の本番運用の解説が示すとおりcompose.production.yamlのような別ファイルに書き、-fで順に重ねます。複数ファイルの解説のとおり、overrideを自動で読むのは-fを省いたときだけです。同ページが本番で変える項目に挙げるのは、アプリのコードのバインドマウントを外す、ポートを変える、環境変数を変える、restart: alwaysなどの再起動ポリシーを付ける、ログ収集のサービスを足す、の5つです。
# 共通定義に本番差分を重ねて起動する
docker compose -f compose.yaml -f compose.production.yaml up -d
# 重ねた結果を事前に確かめる
docker compose -f compose.yaml -f compose.production.yaml config
# コードを変えたあとwebだけ作り直す(DBやキャッシュは触らない)
docker compose -f compose.yaml -f compose.production.yaml build web
docker compose -f compose.yaml -f compose.production.yaml up --no-deps -d web
profilesによる開発用サービスの選択とCompose Watchによる変更反映
profilesは、管理画面やテスト用のサービスを必要なときだけ起動する仕組みです。サービスにprofiles: [debug]と書くと、通常のupでは起動せず、docker compose --profile debug upか環境変数COMPOSE_PROFILES=debugで有効になります。profilesを書いていないサービスは常に起動します。
Compose Watchは、ホスト側のファイルの変更を検知してコンテナへ反映する機能で、サービスのdevelop.watchにルールを書きます。developのリファレンスが定めるactionは5つです。
| action | 変更を検知したときの動き | 向くファイル |
|---|---|---|
| sync | コンテナへファイルを同期 | ホットリロード対応のソース |
| rebuild | イメージを作り直して置換 | package.jsonなど依存定義 |
| sync+restart | 同期してから再起動 | 設定ファイル |
| sync+exec | 同期してからコマンド実行 | 同期後に処理が要るもの |
| restart | コンテナを再起動 | 同期が不要な変更 |
services:
api:
build: .
command: npm start
develop:
watch:
- action: sync
path: ./api
target: /src/api
initial_sync: true
ignore:
- node_modules/
- action: rebuild
path: package.json
起動はdocker compose watchかdocker compose up --watchです。ignoreのパターンは、Compose Watchの解説によればプロジェクトの直下からではなく、そのルールのpathからの相対で解釈されます。上の例のnode_modules/は./api/node_modules/を指します。エディタごと環境を揃えたいならDev Container(devcontainer)のメリットとはの仕組みと組み合わせられます。
pre_startによるサービス起動前のマイグレーション
pre_startはv5.3.0で入った初期化コンテナの仕組みです。servicesリファレンスによれば、各ステップは使い捨てのコンテナで宣言順に最後まで実行され、すべて終了コード0で終わったときだけサービスのコンテナが起動します。ステップはdepends_onの条件を満たしたあとに、サービスと同じネットワークとボリュームで動くので、マイグレーションや権限調整に向きます。
services:
app:
image: myapp:latest
depends_on:
db:
condition: service_healthy
pre_start:
- command: ["./manage.py", "migrate"]
- image: busybox:1.37
command: ["sh", "-c", "chown -R 1000:1000 /data"]
volumes:
- data:/data
db:
image: postgres:18
environment:
POSTGRES_PASSWORD: development-only
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
interval: 2s
timeout: 5s
retries: 10
volumes:
data:
imageを省いたステップはサービス本体と同じイメージで動きます。指定できるのはほかにuser・privileged・working_dir・environment・per_replicaです。一度成功したステップは、定義が変わるかサービスが作り直されるまで、次のupでも再起動ポリシーによる再起動でも走りません。
ステップをexit 3で終わるように書き換えてup -dすると、pre_start[0] exited with code 3と表示され、サービスのコンテナはCreatedのまま起動しませんでした。失敗したステップのコンテナは調査用に残る(retained for inspection)ので、docker logsで原因を見たら手で消します。v5.3.0より前のComposeでは使えないため、チームとCIの版を先に揃えてください。
Docker Composeで足りる範囲とKubernetesへ移す境界
Composeは1台のホストの中で完結する道具です。移行するかどうかは、規模ではなく要件で決めます。
Composeのまま運用してよい条件
次をすべて満たすなら、Composeのまま運用して差し支えありません。
- アプリケーションが1台のホストに収まり、台数を増やして負荷を分ける要件がない
- 数分程度の停止を許容でき、無停止での入れ替えまでは求められない
- compose.yamlから依存関係と運用手順を把握でき、担当者が構成変更を管理できる
- 開発・検証環境、CIの結合テスト、社内向けや小規模なサービスの本番である
落ちたコンテナの自動復旧はrestartポリシー(no・always・on-failure・unless-stopped)に頼るだけで、サーバー自体が止まれば全サービスが止まります。CIで使う場合は、GitHub Actionsのサービスコンテナ(services)で同じ構成を組む方法もあります。
Kubernetesへ移す条件とComposeでよくある失敗
前の節の条件が1つでも外れたら、オーケストレーション基盤への移行を検討します。Kubernetesの公式概要は、自己修復や自動ロールアウトを機能に挙げています。移行先の全体像はKubernetes(クバネティス)とは?仕組み・メリット・デメリットとDockerとの違いをわかりやすく解説、判断の軸はコンテナオーケストレーションとは?仕組み・ツール比較と料金、自社に要るかの判断にまとめています。クラウド上でのコンテナ基盤の設計や移行を相談したい場合は、AWS・Google Cloud・Azureのインフラ構築支援で構成の検討から相談できます。
Composeで避けたい失敗は、開発用のcompose.yamlをデバッグ用ポートや平文のパスワードごと本番へ持ち込むことで、override・-fで差分を分ければ防げます。ホストのCPUやメモリを使い切っている場合は、--scaleでコンテナ数を増やしてもホスト全体の計算資源は増えません。ホストに余力があり、単一プロセスがボトルネックの場合は、同一ホスト内の増設が有効なこともあります。そうなったら移行の時期です。
Docker Composeに関するよくある質問
DockerとDocker Composeの違いは何ですか?
Docker Engineはコンテナを1つずつ実行する基盤で、Docker Composeは複数コンテナの構成と起動順をcompose.yamlで宣言してまとめて扱うツールです。
docker-composeとdocker composeの違いは何ですか?
ハイフン付きはPython製で保守が終わったV1、スペース区切りはGo製の現行版です。既存のdocker-compose.ymlは読めますが、コンテナ名の区切りがproj_db_1からproj-db-1のようにハイフンへ変わるため、名前を決め打ちしたスクリプトは移行時に直します。
Docker ComposeとKubernetesの違いは何ですか?
Composeは1台のホストの中で複数コンテナを動かす道具で、Kubernetesは複数ホストへの配置・自動復旧・自動スケールまで担う基盤です。
Docker Composeはどうやってインストールしますか?
Docker Desktopを入れれば、Windows・macOS・Linuxのどれでも同梱されています。Desktopを使わないLinuxでは、Dockerの公式リポジトリを登録したうえでsudo apt-get install docker-compose-plugin(RPM系はyum)を実行し、docker compose versionで版を確かめます。
compose.yamlとdocker-compose.ymlはどちらを使うべきですか?
新しく作るならcompose.yamlです。docker-compose.ymlも後方互換で読まれるので既存のファイルを急いで改名する必要はありませんが、両方を同じディレクトリに置くとcompose.yamlが優先され警告が出ます。改名するなら古い方は消してください。
関連記事
- Dockerとは|仮想マシンとの違い・必要スペック・Desktop/Engineの違いとインストール手順【2026年10月】
- Dockerの仕組みを図解:containerd・runc・namespaces・ネットワーク・Composeの内部を実測で解説
- Dockerfileとは|書き方・ファイル名(拡張子)・主要命令とsyntaxの版を実測で解説【2026年10月】
- DockerでMySQLを構築する手順|latestが26系へ変わったタグ選定とcompose定義・初期化を実装目線で解説
- Kubernetes(クバネティス)とは?仕組み・メリット・デメリットとDockerとの違いをわかりやすく解説