Contents
スポンサードリンク
Docker Compose が提供する主要バージョン
| バージョン | 配布形態 | 主な特徴 | サポートしている Compose file バージョン |
|---|---|---|---|
v1 (docker‑compose) |
独立した実行ファイル（Python で実装） | - docker-compose コマンドとして呼び出す- 更新は比較的遅い（2023 年以降、機能追加は停止） - version: キーが必須 |
2.0 – 3.9 （4.x 系は未対応） |
v2 (docker compose) |
Docker CLI に統合されたサブコマンド | - Docker Engine と同時に配布され、アップデートは Engine のリリースと連動 - version: キーは任意（Compose Spec が推奨）- --compatibility フラグで v1 互換モードが利用可 |
2.0 – 3.9 + Compose Spec (4.0 以降) |
| v2 (Docker Desktop 内蔵版) | Docker Desktop（macOS / Windows）に同梱 | - GUI の「Settings → General」から有効化／無効化を切り替えられる - デフォルトで Use Docker Compose V2 がオンになっていることが多い |
全ての公式 Spec (4.0+) をサポート（ただし Engine バージョンに依存） |
ポイント
2026‑04‑26 時点 では、Compose V2 が「最新の Compose Spec」を包括的にサポートしています。version:キーは非推奨となり、ファイル冒頭に記述しなくても自動で最新 Spec とみなされます（公式ドキュメント参照）。
主要バージョン間の違いをざっくりまとめ
| 観点 | Compose V1 (docker‑compose) |
Compose V2 (docker compose) |
|---|---|---|
| 実装言語 | Python | Go（Docker Engine と同一） |
| インストール方法 | pip install docker-compose、Homebrew の docker-compose など |
Docker Desktop に同梱、または docker パッケージに含まれる |
| CLI 表記 | docker‑compose up -d |
docker compose up -d |
| 更新頻度 | 2025 年以降は機能追加停止（バグフィックスのみ） | エンジンと同時に毎月リリース |
| Compose file バージョン | 2.x – 3.9（version: 必須） |
2.x – 3.9 + Spec (4.0+)（version: 任意） |
公式マトリクスの見つけ方と活用例
Docker の公式ドキュメントは 「Compose file versioning」 ページに、Engine バージョン ↔ Compose file バージョンの互換性表（Compatibility matrix）を掲載しています。
手順
- ブラウザで以下の URL を開く
https://docs.docker.com/compose/compose-file/versioning/ - ページ中段にある “Compatibility matrix”（エンジン ↔ ファイルバージョン）を探す。表は Markdown 形式で掲載されているので、コピーしてローカルのメモに貼り付けても OK。
- 自分が使用している Docker Engine バージョン と、Compose ファイルに書かれた（もしくは省略した）バージョンを照合する。
例
- Engine が24.0.xの場合、公式マトリクスは4.0以上の Compose Spec を「Supported」と表示しています。
- 同じく Engine が23.0.x以前だと、一部の4.0機能が “Unsupported” と記載されることがあります。
マトリクスの更新頻度
公式ページは Docker の各リリースサイクル（約月1回）に合わせて自動更新 されます。そのため、CI パイプラインやドキュメントで「最新マトリクスを参照する」旨を書いておけば、将来的なバージョンずれのリスクが低減します。
CLI で取得できるバージョン情報とその読み取り方
1. Compose（クライアント）バージョン確認
|
1 2 3 |
$ docker compose version --short Docker Compose v2.27.0 |
v2.27.0が CLI 側の実装バージョンです。- GitHub のリリースノート（https://github.com/docker/compose/releases）で、対応する Compose file バージョンをすぐに確認できます。
2. Docker Engine（サーバー）バージョン確認
|
1 2 3 |
$ docker version --format '{{.Server.Version}} {{.Server.APIVersion}}' 24.0.5 1.45 |
| フィールド | 内容 |
|---|---|
Server.Version |
実際に稼働している Docker Engine のリリース番号（例：24.0.5） |
Server.APIVersion |
Engine が提供する API バージョン（例：1.45） |
ポイント
公式マトリクスは Engine.Version に基づいているので、上記コマンドで得た数値を直接照合してください。
3. 一括確認用シェルスニペット（CI 用）
|
1 2 3 4 5 6 7 8 9 10 11 12 |
#!/usr/bin/env bash set -euo pipefail COMPOSE_VER=$(docker compose version --short | awk '{print $3}') ENGINE_VER=$(docker version --format '{{.Server.Version}}') echo "Compose: ${COMPOSE_VER}" echo "Engine : ${ENGINE_VER}" # 例：マトリクス表へのリンクを自動生成 echo "Check compatibility at:" echo "https://docs.docker.com/compose/compose-file/versioning/#compatibility-matrix" |
このスクリプトは GitHub Actions / GitLab CI の pre‑flight ステップに組み込めば、プルリクエストごとにバージョン不整合を即座に検知できます。
Compose ファイルの検証・デバッグ手順
1. 基本的な構文チェック
|
1 2 |
$ docker compose -f docker-compose.yml config --quiet |
- 出力が無い → YAML が正しく解析され、Compose がサポートしていることを示す。
- エラーメッセージ が表示されたら、行番号とキー名に注目し、公式マトリクスで「Supported」かどうか確認。
2. --compatibility フラグの活用例
|
1 2 |
$ docker compose --compatibility -f docker-compose.yml up -d |
- v1 用のオプション（例：
restart,scale）を自動的に V2 が変換してくれる。 - 注意：実行時のみ有効で、ファイル自体は変更されません。長期的な互換性確保にはファイルを書き換えるべきです。
3. よくあるエラーと対策
| エラーメッセージ | 原因例 | 推奨対処 |
|---|---|---|
Unsupported config option for services.web: "restart_policy" |
restart_policy は v1 のみで、V2 では restart に相当 |
docker compose version が最新か確認し、--compatibility を一時的に使用 |
version in "./docker-compose.yml" is invalid |
version: キーが古い（例：2.0）または削除したのに残っている |
version: 行を削除し、Compose Spec に沿った書き方へ変更 |
services.<name>.build.context is not a directory |
ビルドコンテキストパスが存在しない／権限不足 | パスを正しく設定し、Engine バージョンが context: をサポートしているか確認 |
互換性が合わないときの対処法とベストプラクティス
選択肢① – フラグで旧形式エミュレート
|
1 2 |
docker compose --compatibility up -d |
- メリット：即時に稼働させられる。
- デメリット：根本的なファイル更新が行われないため、将来のバージョンアップで再度同様の問題が発生しやすい。
選択肢② – Compose V2 の特定バージョンに固定
macOS（Homebrew）で安全にインストールする例
|
1 2 3 4 5 6 7 8 9 |
# 1. Homebrew の tap を最新化 brew update # 2. docker (Engine) と compose v2 が同梱されたパッケージをインストール brew install docker # 3. 必要なら特定バージョンの CLI を取得（公式 formula は `docker` のみ） # 任意のバージョンは GitHub リリースページからダウンロードして PATH に配置 |
ポイント
Homebrew にはdocker-compose@2.xxといった名前のフォーミュラは存在しません。Compose V2 は Docker 本体に同梱されるか、公式 GitHub リリースから直接バイナリを取得します。
Linux（apt / yum）で特定バージョンを入手
|
1 2 3 4 5 6 |
# Ubuntu 例 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io # 必要なら GitHub の release ページから v2.x 系の CLI バイナリを上書き |
選択肢③ – ファイルを最新 Compose Spec にアップグレード
version:行を削除（Spec が自動適用される）- 非推奨オプションの置換例
| 旧オプション | 新しい書き方 (Compose Spec) |
|---|---|
deploy: （Swarm 固有） |
profiles: と resources.limits に分割 |
restart: always |
restart_policy: → { condition: any }（V2 でもサポート） |
links: |
サービス間はネットワーク名で暗黙的に解決できるので削除 |
- 自動変換ツール（任意）
compose-goのconvertコマンドや、コミュニティ製のdocker-compose-upgradeスクリプトを活用すると、大量ファイルでも一括変換が可能です。
ベストプラクティスまとめ
| 項目 | 実装例 / 推奨ツール |
|---|---|
| CI での構文チェック | docker compose config --quiet を PR ビルドに組み込む |
| 定期的なバージョン監査 | 半年ごとに docker compose version && docker version の出力を公式マトリクスと比較 |
| ドキュメントの一元管理 | 社内 Wiki に「Compose Spec への移行ガイド」ページを作成し、リンク先は公式 Docs（常に最新） |
| バイナリの取得方法統一 | macOS は Homebrew、Linux はパッケージマネージャ＋必要なら GitHub リリースから直接ダウンロード |
インストール時の注意点（macOS・Linux）
macOS（Homebrew）
| 手順 | コマンド |
|---|---|
| 1️⃣ Homebrew の更新 | brew update |
| 2️⃣ Docker Engine と Compose V2 を同梱したパッケージをインストール | brew install docker |
| 3️⃣ （任意）Docker Desktop の有無を確認し、Settings → General の “Use Docker Compose V2” がオンかチェック | GUI 操作 |
注意：Homebrew に
docker-compose@2.xxといった名前のフォーミュラはありません。バージョンを固定したい場合は公式 GitHub リリースからバイナリをダウンロードし、PATH の先頭に配置してください。
Linux（Debian / Ubuntu 系）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# 公式リポジトリのセットアップ sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg # Docker の GPG 鍵とリポジトリを追加 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \ https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # パッケージインストール sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io # インストール直後に Compose V2 が同梱されているか確認 docker compose version --short |
ポイント：
docker-compose（v1）を別途インストールしたい場合はpip install docker-compose==1.29.2などで明示的にバージョン指定が必要です。ただし、将来的な保守性を考えると Compose V2 への移行を強く推奨します。
まとめ
| 項目 | 要点 |
|---|---|
| 主要バージョン | V1 は 2.x–3.9、V2 はそれに加えて Compose Spec (4.0+) を公式サポート |
| 互換性確認 | 公式「Compose file versioning」ページの Compatibility matrix が最も信頼できる情報源 |
| バージョン取得方法 | docker compose version と docker version --format '{{.Server.Version}}' を組み合わせてチェック |
| 構文・オプション検証 | docker compose config --quiet で即座にエラーを捕捉。--compatibility フラグは一時的な回避策 |
| 不一致時の対処 | 1. --compatibility で旧形式エミュレート、2. 必要なら V2 の特定バージョンへ固定、3. ファイルを最新 Spec にアップグレード |
| インストール注意点 | Homebrew では docker-compose@… といったフォーミュラは存在しない。Docker 本体に同梱された Compose V2 を利用するか、公式バイナリを直接取得 |
最終的な推奨
- 新規プロジェクトは必ず Compose V2 + Spec（version:なし） で作成。
- 既存のdocker-compose.ymlは CI パイプラインにdocker compose config --quietを組み込み、定期的にエラーが出ていないか確認する。
- 6 ヶ月ごとに Docker Engine と Compose のバージョンを公式マトリクスと照らし合わせ、必要ならアップデートまたはファイルの書き換えを実施する。
これで Docker Compose のバージョン体系・互換性確認手順・不整合時の対処法 が網羅的に把握できるはずです。ぜひ日々の開発フローや CI/CD パイプラインに組み込んで、安定したコンテナ運用を実現してください。
スポンサードリンク