Contents
Docker Compose V2 の概要とプラグイン化のポイント
Docker Compose V2 は、2024 年に 一般提供（GA） が開始された公式 CLI プラグインです。従来は docker‑compose という独立バイナリで提供されていましたが、現在は Docker Engine のサブコマンドとして docker compose と呼び出せます。この章では、プラグインアーキテクチャと Compose Specification（以下「Compose Spec」）への対応が実務に与える効果を整理します。
プラグインアーキテクチャとは
Docker CLI のプラグイン機構は、バイナリを個別のディレクトリに配置するだけで新しいサブコマンドを追加できる仕組みです。Compose V2 はこの方式で実装されているため、以下のようなメリットがあります。
-
独立したアップデート
Docker Engine 本体とは別にプラグインだけを更新できるため、バージョン管理がシンプルになります。 -
軽量な配布
プラグインは数 MB 程度の単一ファイルで提供され、/usr/local/libexec/docker/cli-plugins/に配置すれば自動的に認識されます。 -
CI 環境への導入が容易
Docker の公式イメージにはプラグインが同梱されていないことが多いため、curlやaptで取得してパスに置くだけで使用可能です。
実例
bash
$ docker compose version
Docker Compose version v2.30.0
上記コマンドはプラグインが正しく配置されていることを示します。
Compose Specification への対応
Compose Spec は、Docker が策定した「Compose ファイルの共通スキーマ」です。V2 はこの仕様に ほぼ完全に準拠しており、次のような利点があります。
-
マルチクラウドでの一貫性
同じdocker-compose.ymlを Kubernetes の Helm Chart や Terraform の Docker Provider と連携させても、構文エラーが発生しにくくなります。 -
標準化された出力形式
docker compose config --format jsonによって JSON スキーマを取得でき、外部ツールとの自動連携が容易です。
実例
bash
$ docker compose config --format json | jq .
{
"services": { ... },
"networks": { ... }
}
V1 と V2 のコマンド構造・オプション比較
Docker Compose V1（docker-compose）から V2（docker compose）への移行は、基本的に サブコマンドの呼び出し方が変わるだけ です。ただし、スクリプトや CI の設定によっては微調整が必要になるケースがあります。
コマンド置換の基本方針
- ローカル環境 – シェルエイリアスで
docker-composeをdocker composeにリダイレクトする。 - CI 環境 – エイリアスが効かないことが多いため、ラッパースクリプト（小さなシェルファイル）を作成し、PATH の先頭に配置する。
この二段階アプローチで、既存のコマンド呼び出しを変更せずに V2 へ移行できます。
エイリアスとラッパースクリプトの実装例
bash / zsh 用エイリアス（ローカル）
|
1 2 3 |
# ~/.bashrc または ~/.zshrc に追記 alias docker-compose='docker compose' |
設定後に source ~/.bashrc すれば、ターミナル上の全ての docker-compose … が自動的に V2 に置き換わります。
fish 用エイリアス（ローカル）
|
1 2 3 |
# ~/.config/fish/config.fish に追記 alias docker-compose='docker compose' |
CI 用ラッパースクリプト（共通）
プロジェクトのルートに docker-compose という名前で以下を作成し、実行権限を付与します。
|
1 2 3 |
#!/usr/bin/env sh exec docker compose "$@" |
CI のジョブでは PATH=$PWD:$PATH を設定すれば、既存のスクリプトがそのまま動作します。
公式インストール手順（Ubuntu、Windows、macOS）
ここでは 2024 年時点での最新情報 に基づき、主要 OS 向けに推奨されるインストールフローをまとめます。各手順は公式ドキュメントとリンク先を併記していますので、実行前に最新情報をご確認ください。
Ubuntu 系 Linux（22.04・24.04）
Docker の公式リポジトリから Engine と Compose プラグインを同時に導入できます。APT による管理は自動更新や依存関係解決が保証されるため、エンタープライズ環境でも安全です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# 1. GPG 鍵の追加 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \ sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 2. リポジトリ情報の登録（Ubuntu のコードネームは `$(lsb_release -cs)` が自動取得） echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \ https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 3. パッケージ情報更新 & インストール sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin |
インストール後、以下でプラグインの有効化を確認します。
|
1 2 3 |
$ docker compose version Docker Compose version v2.30.0 |
参照: https://docs.docker.com/engine/install/ubuntu/
Windows（Docker Desktop + WSL2）
Windows では Docker Desktop が GUI と CLI を一体化して提供しています。Compose V2 はデフォルトで同梱されており、設定画面から有効化できます。
- Docker Desktop のインストール（公式サイトから最新バージョンを取得）
https://www.docker.com/products/docker-desktop/ - 設定 → General で 「Use Docker Compose V2」 にチェック。
- PowerShell または WSL2 ターミナルで
docker compose versionを実行し、バージョンが表示されれば完了です。
ポイント：WSL2 環境でも同一の Docker Desktop がバックエンドになるため、Linux と同様にプラグインを利用できます。
macOS（Apple Silicon 対応）
macOS 12 以降では、Docker Desktop for Mac の Apple Silicon ビルドが推奨されます。手順は Windows とほぼ同一です。
- Docker Desktop for Mac (Apple Silicon) を公式サイトからダウンロードしてインストール
https://www.docker.com/products/docker-desktop/ - Preferences → General で 「Use Docker Compose V2」 を有効化。
- ターミナルで
docker compose versionを確認。
参照: https://docs.docker.com/desktop/mac/install/
移行作業：Compose ファイルの更新と互換性チェック
V1 から V2 へ移行する際に注意すべきは、非推奨項目の削除 と 長形構文（long syntax）への変換 です。これらを行ったうえで公式ツール compose-spec-check を活用すると、移行時のミスを低減できます。
非推奨項目とトップレベル構文の変更例
-
version:キーは不要
Compose Spec は外部でバージョン管理されるため、ファイルから削除します。 -
短形構文 → 長形構文への置換
ports,volumes,configs,secretsなどはキー名と属性を明示的に書く長形が推奨されます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# V1（旧形式） version: "3.8" services: web: image: nginx:latest ports: - "8080:80" # V2（新形式・長形構文） services: web: image: nginx:latest ports: - target: 80 # コンテナ側ポート published: 8080 # ホスト側ポート protocol: tcp mode: host |
補足：
networks,secretsも同様に長形で記述すると、Compose Spec の検証ツールがエラーを出さなくなります。
compose-spec-check の利用方法
公式の検証ツールは Go 言語環境または Docker イメージからインストールできます。どちらでも同等の結果が得られます。
Go バイナリでインストール（ローカル向け）
|
1 2 |
go install github.com/docker/compose-spec/check@latest # $HOME/go/bin が PATH に入っている前提 |
Docker イメージで実行（CI 向け）
|
1 2 3 |
docker run --rm -v $(pwd):/work -w /work \ ghcr.io/docker/compose-spec-check:latest ./docker-compose.yml |
検証結果は JSON またはテキストで出力され、エラー箇所が具体的に示されます。CI パイプラインではステップを失敗させるだけで品質担保が可能です。
ローカルテストフローと典型的なエラー
| 検証項目 | 手順例 | 代表的なエラーメッセージ | 対処法 |
|---|---|---|---|
| プラグイン有効化 | docker compose version |
docker: 'compose' is not a docker command. |
/usr/local/libexec/docker/cli-plugins/ が PATH に含まれているか確認し、必要なら export PATH=$PATH:/usr/local/libexec/docker/cli-plugins を追加 |
| ファイル構文 | docker compose config |
Invalid interpolation format |
環境変数の書式 ${VAR} が正しいか、エスケープが不要か確認 |
| ネットワーク競合 | docker network ls |
network with name xxx already exists |
docker compose down --remove-orphans で残存ネットワークを削除 |
| シークレットロード | docker compose up -d |
failed to load secret: file not found |
secrets: の file: パスはホスト側の絶対パスで指定し、CI でも同一ディレクトリに配置 |
上記チェックをローカルで実施したうえで compose-spec-check を併用すれば、移行後のサービス停止リスクを大幅に低減できます。
CI/CD パイプラインへの適用例とトラブルシューティング
CI 環境では Docker イメージに Compose プラグインが同梱されていないケースが多いため、プラグイン取得ステップ を明示的に追加します。以下は主要ツール別の実装例です。
GitHub Actions での設定例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
name: CI on: push: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 # Docker Buildx のセットアップ（公式アクション） - name: Set up Docker Buildx uses: docker/setup-buildx-action@v2 # Compose V2 プラグイン取得 - name: Install Docker Compose V2 plugin run: | PLUGIN_URL="https://github.com/docker/compose/releases/download/v2.30.0/docker-compose-linux-x86_64" curl -sSL $PLUGIN_URL -o docker-compose sudo mkdir -p /usr/local/libexec/docker/cli-plugins/ sudo mv docker-compose /usr/local/libexec/docker/cli-plugins/docker-compose sudo chmod +x /usr/local/libexec/docker/cli-plugins/docker-compose # 例: テスト実行 - name: Run integration tests run: | docker compose up -d --build docker compose exec web pytest |
ポイント：プラグイン取得はバージョンを固定せず
latestタグや GitHub API で動的に取得するようにすれば、将来の更新にも自動対応できます。
GitLab CI と Azure Pipelines の留意点
| プラットフォーム | 主な設定ポイント |
|---|---|
| GitLab CI | image: docker:latest に加えて docker:dind サービスを使用し、before_script で同様にプラグインバイナリを /usr/local/libexec/docker/cli-plugins/ に配置。 |
| Azure Pipelines | Ubuntu エージェント上で apt-get install -y curl 後、プラグイン取得スクリプトを実行。script: ブロック内で docker compose version を確認してからビルド・テストを進める。 |
いずれの場合も PATH の設定 が重要です。プラグインディレクトリが $PATH に含まれていないと、docker compose コマンドは認識されません。
ロールバック手順と FAQ
V1 へ戻す手順（緊急時）
|
1 2 3 4 5 6 7 8 9 10 11 |
# 1. プラグイン削除 sudo rm /usr/local/libexec/docker/cli-plugins/docker-compose # 2. V1 バイナリを取得して配置 curl -L "https://github.com/docker/compose/releases/download/v1.29.2/docker-compose-$(uname -s)-$(uname -m)" \ -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose # 3. エイリアス解除（必要に応じて） unalias docker-compose # bash/zsh の場合 |
よくある質問と対処法
| 質問 | 回答 |
|---|---|
| Compose Spec 検証でエラーが出る | エラーメッセージに示された項目を長形構文へ書き換える。特に ports, volumes の target/source が必須になる点に注意。 |
docker: 'compose' is not a docker command. |
プラグインが正しいディレクトリに配置されていないか、PATH に含まれていません。export PATH=$PATH:/usr/local/libexec/docker/cli-plugins をシェル設定へ追記してください。 |
| CI で古い V1 が走ってしまう | ワークフロー冒頭でプラグイン取得ステップを必ず実行し、docker compose version の出力でバージョンを確認することで防げます。 |
| シークレットがロードできない | V2 では secrets: 定義の file: パスはホスト側の絶対パスが必要です。また、Docker Desktop の設定で「File sharing」対象に含めることを忘れずに。 |
| ネットワーク名衝突エラー | docker compose down --remove-orphans をジョブ終了時に必ず実行し、残存リソースをクリーンアップします。 |
まとめ
Docker Compose V2 は プラグイン化 と Compose Specification のフルサポート によって、従来の docker-compose よりも柔軟かつ標準的な運用が可能になりました。移行作業は以下の３ステップで完了します。
- プラグイン導入とコマンド置換（エイリアス／ラッパースクリプト）
- Compose ファイルの非推奨項目削除・長形構文への変換 と
compose‑spec‑checkで検証 - CI/CD パイプラインへプラグイン取得ステップを組み込み、ロールバック手順も用意
公式ドキュメントと本稿のチェックリストを併用すれば、サービス停止リスクを最小化しつつ最新の Docker エコシステムに対応できます。ぜひ実務で活用してください。