Docker Compose V2 のインストールと移行ガイド【Linux対応】

2026年4月24日

Contents

1 1. 前提条件と対象 OS・Docker Engine バージョン
2 2. Docker Compose V2 プラグインのインストール方法
3 3. 既存 docker‑compose から docker compose への移行手順
4 4. CI/CD パイプラインへの適用とベストプラクティス
5 5. トラブルシューティングとロールバックガイド
6 6. 参考リンク・公式情報
7 7. まとめ（最終チェックリスト）

スポンサードリンク

1. 前提条件と対象 OS・Docker Engine バージョン

1‑1. 要点（冒頭にまとめ）

Docker Engine が v20.10.13 以上 の環境であれば、公式リポジトリから docker-compose-plugin をインストールするだけで V2 が利用可能。
対象 OS は Ubuntu 22.04 LTS、Debian 12、CentOS Stream 9、Rocky Linux 8、Amazon Linux 2023 の最新版を想定。
バージョンが古い場合は 公式スクリプトでバイナリを手動配置 するか、docker-compose-plugin パッケージを別途取得して /usr/lib/docker/cli-plugins/ に配置する必要がある。

1‑2. サポート対象 Linux ディストリビューション

ディストリビューション	推奨 Docker Engine バージョン	主なパッケージマネージャ
Ubuntu 22.04 LTS	20.10.13 以上	`apt`
Debian 12	20.10.13 以上	`apt`
CentOS Stream 9	20.10.13 以上	`dnf` / `yum`
Rocky Linux 8	20.10.13 以上	`dnf` / `yum`
Amazon Linux 2023	20.10.14 以上	`yum`

ポイント：Docker Engine が上記バージョン未満の場合は、後述の「プラグイン手動配置」セクションを必ず実施してください。

1‑3. Docker Engine バージョン別インストール要件

バージョン	インストール方法
20.10.13 以上	`docker-ce` パッケージに同梱された `/usr/lib/docker/cli-plugins/docker-compose` が自動配置される。
20.10.12 以下	`docker-compose-plugin` を別途取得し、手動で上記パスへコピーする必要がある。

1‑4. 前提条件チェックリスト

# (1) OS のバージョン確認
cat /etc/os-release

# (2) Docker Engine のバージョン確認
docker version --format '{{.Server.Version}}'

# (3) 現在インストールされている docker‑compose バイナリと権限の確認
which docker-compose &amp;&amp; ls -l $(which docker-compose)

# (1) OS のバージョン確認

cat /etc/os-release

# (2) Docker Engine のバージョン確認

docker version --format '{{.Server.Version}}'

# (3) 現在インストールされている docker‑compose バイナリと権限の確認

which docker-compose && ls -l $(which docker-compose)

例: Ubuntu 22.04、Docker Engine 20.10.14 が表示されたら プラグイン同梱版 のインストールが可能です。
バージョン取得に失敗した場合は、公式インストールガイド（Docker Engine インストール手順）を参照してください。

2. Docker Compose V2 プラグインのインストール方法

2‑1. 要点

apt / dnf で公式リポジトリから docker-compose-plugin をインストールすれば、最も簡単かつ推奨される手順。
リポジトリにパッケージが無い古い環境は、GitHub の最新リリースを取得してバイナリを直接配置 するスクリプトで対処できる。
pip によるインストールは Compose V1（Python 製） 用であり、V2 の機能は利用できないため非推奨。

公式情報へのリンク
- Docker Compose plugin: https://docs.docker.com/compose/install/
- GitHub Releases API (最新タグ取得): https://api.github.com/repos/docker/compose/releases/latest

2‑2. apt / dnf によるインストール手順

Ubuntu / Debian（apt）

# 1&#xfe0f;&#x20e3; Docker の公式リポジトリを追加（未設定の場合）
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

curl -fsSL https://download.docker.com/linux/ubuntu/gpg |
  sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

echo &quot;deb [arch=$(dpkg --print-architecture) \
signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable&quot; |
  sudo tee /etc/apt/sources.list.d/docker.list &gt; /dev/null

# 2&#xfe0f;&#x20e3; パッケージリストを更新し、Docker Engine と Compose プラグインを同時にインストール
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 1️⃣ Docker の公式リポジトリを追加（未設定の場合）

sudo apt-get update

sudo apt-get install -y ca-certificates curl gnupg lsb-release

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

# 2️⃣ パッケージリストを更新し、Docker Engine と Compose プラグインを同時にインストール

sudo apt-get update

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

CentOS / Rocky Linux（dnf / yum）

# 1&#xfe0f;&#x20e3; Docker の公式リポジトリ設定
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 2&#xfe0f;&#x20e3; Docker Engine と Compose プラグインをインストール
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 1️⃣ Docker の公式リポジトリ設定

sudo dnf install -y dnf-plugins-core

sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 2️⃣ Docker Engine と Compose プラグインをインストール

sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

注意：docker-compose-plugin がリポジトリに存在しない古い OS（例: CentOS 7）では、次節の「公式スクリプト」方式を利用してください。

2‑3. 公式インストールスクリプトによる手動配置

# jq がインストールされていなければ取得
sudo apt-get install -y jq   # Ubuntu/Debian 系の場合
# sudo dnf install -y jq     # RHEL/CentOS 系の場合

# GitHub の最新リリースタグを取得（例: v2.23.0）
DOCKER_COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | jq -r .tag_name)

# バイナリのダウンロードと配置
sudo curl -SL &quot;https://github.com/docker/compose/releases/download/${DOCKER_COMPOSE_VERSION}/docker-compose-linux-$(uname -m)&quot; \
  -o /usr/lib/docker/cli-plugins/docker-compose

# 実行権限を付与
sudo chmod +x /usr/lib/docker/cli-plugins/docker-compose

# jq がインストールされていなければ取得

sudo apt-get install -y jq # Ubuntu/Debian 系の場合

# sudo dnf install -y jq # RHEL/CentOS 系の場合

# GitHub の最新リリースタグを取得（例: v2.23.0）

DOCKER_COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | jq -r .tag_name)

# バイナリのダウンロードと配置

sudo curl -SL "https://github.com/docker/compose/releases/download/${DOCKER_COMPOSE_VERSION}/docker-compose-linux-$(uname -m)" \

-o /usr/lib/docker/cli-plugins/docker-compose

# 実行権限を付与

sudo chmod +x /usr/lib/docker/cli-plugins/docker-compose

スクリプトのポイント

自動取得：DOCKER_COMPOSE_VERSION は実行時に最新タグを取得するため、バージョン固定による陳腐化リスクが低減されます。
パス：Docker CLI がプラグインを検索する標準ディレクトリは /usr/lib/docker/cli-plugins/ です。

2‑4. インストール確認コマンド

docker compose version

1 2	docker compose version

期待される出力例（バージョンは実行時の最新）
Docker Compose version v2.23.0

3. 既存 `docker‑compose` から `docker compose` への移行手順

3‑1. 要点まとめ

エイリアスは一時的な切り替えに便利だが、永続的に利用したい場合は シンボリックリンク が推奨される。
旧バイナリをバックアップすれば、障害発生時に即座に V1 にロールバック可能。
docker-compose.yml は概ね互換性があるが、V2 の新機能（profiles、--watch 等）を活用すると運用効率が向上する。

3‑2. エイリアスとシンボリックリンクの比較

方法	永続性	メリット	デメリット
シェルエイリアス (`alias dc='docker compose'`)	セッションごとに設定が必要（`.bashrc` 等へ追記すれば永続化）	手軽に導入可能、環境変数やオプションの追加が簡単	シェル外（CI スクリプト等）では無効
シンボリックリンク (`ln -s /usr/lib/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose`)	ファイルシステム上に常駐し、全プロセスで有効	既存の `docker-compose` コマンドがそのまま V2 に置き換わる	バックアップ・削除作業が必要

推奨手順（シンボリックリンク）

# 1&#xfe0f;&#x20e3; 既存バイナリの場所を確認
which docker-compose   # 例: /usr/local/bin/docker-compose

# 2&#xfe0f;&#x20e3; バックアップ取得
sudo mv /usr/local/bin/docker-compose /usr/local/bin/docker-compose.v1.bak

# 3&#xfe0f;&#x20e3; シンボリックリンク作成
sudo ln -s /usr/lib/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose

# 4&#xfe0f;&#x20e3; 動作確認
docker compose version   # V2 が表示されれば完了

# 1️⃣ 既存バイナリの場所を確認

which docker-compose # 例: /usr/local/bin/docker-compose

# 2️⃣ バックアップ取得

sudo mv /usr/local/bin/docker-compose /usr/local/bin/docker-compose.v1.bak

# 3️⃣ シンボリックリンク作成

sudo ln -s /usr/lib/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose

# 4️⃣ 動作確認

docker compose version # V2 が表示されれば完了

ロールバックは sudo rm /usr/local/bin/docker-compose && sudo mv /usr/local/bin/docker-compose.v1.bak /usr/local/bin/docker-compose で実行できます。

3‑3. `docker-compose.yml` の互換性と V2 推奨機能

基本的な互換性

バージョン宣言 (version: "3"、"3.8" 等) はそのままで動作。
サービス定義やボリューム・ネットワークの書式は従来通り。

新機能サンプル

services:
  web:
    image: nginx:latest
    ports:
      - &quot;8080:80&quot;
    profiles: [&quot;dev&quot;]          # ← 開発環境専用プロファイル
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: example
    profiles: [&quot;prod&quot;]         # ← 本番環境専用プロファイル

# プロファイルを選択して起動
#   docker compose --profile dev up -d
#   docker compose --profile prod up -d

services:

web:

image: nginx:latest

ports:

- "8080:80"

profiles: ["dev"] # ← 開発環境専用プロファイル

db:

image: postgres:15

environment:

POSTGRES_PASSWORD: example

profiles: ["prod"] # ← 本番環境専用プロファイル

# プロファイルを選択して起動

# docker compose --profile dev up -d

# docker compose --profile prod up -d

--watch オプション
bash docker compose up --watch # ソースコード変更時に自動で再デプロイ

3‑4. 移行後の検証フロー

手順	コマンド	確認項目
構文チェック	`docker compose config`	YAML が正しくパースできるか
プラン確認	`docker compose up --dry-run`	生成されるリソース一覧を表示
実行テスト	`docker compose up -d`	コンテナが正常に起動するか
ログ取得	`docker compose logs -f`	起動直後の標準出力でエラーが出ていないか

4. CI/CD パイプラインへの適用とベストプラクティス

4‑1. 要点まとめ

CI 環境でも Docker Engine と Compose V2 を同一バージョンに統一すれば、ローカルで確認した挙動をそのまま再現できる。
GitHub Actions・GitLab CI の公式アクション／イメージを活用し、docker-compose-plugin のインストールを自動化する。
キャッシュの有効活用と 権限設定がビルド時間短縮・安全性向上の鍵。

4‑2. GitHub Actions（Ubuntu 22.04）実装例

name: CI (Docker Compose V2)

on:
  push:
    branches: [ main ]

jobs:
  build-and-test:
    runs-on: ubuntu-22.04
    steps:
      - name: ソースコード取得
        uses: actions/checkout@v3

      # Docker Engine と Buildx のセットアップ（公式アクション）
      - name: Set up Docker + Buildx
        uses: docker/setup-buildx-action@v2

      # Compose V2 プラグインのインストール
      - name: Install Docker Compose plugin (apt)
        run: |
          sudo apt-get update
          sudo apt-get install -y docker-compose-plugin

      # バージョン確認（デバッグ用）
      - name: Verify Compose version
        run: docker compose version

      # ビルド &amp; テスト実行例
      - name: Build services
        run: |
          docker compose build --pull
          docker compose up -d
          docker compose ps
          # 必要に応じてテストスクリプトを実行

name: CI (Docker Compose V2)

on:

push:

branches: [ main ]

jobs:

build-and-test:

runs-on: ubuntu-22.04

steps:

- name: ソースコード取得

uses: actions/checkout@v3

# Docker Engine と Buildx のセットアップ（公式アクション）

- name: Set up Docker + Buildx

uses: docker/setup-buildx-action@v2

# Compose V2 プラグインのインストール

- name: Install Docker Compose plugin (apt)

run: |

sudo apt-get update

sudo apt-get install -y docker-compose-plugin

# バージョン確認（デバッグ用）

- name: Verify Compose version

run: docker compose version

# ビルド & テスト実行例

- name: Build services

run: |

docker compose build --pull

docker compose up -d

docker compose ps

# 必要に応じてテストスクリプトを実行

ポイント解説

docker/setup-buildx-action が Docker Engine（v23 系）と BuildKit を提供。
apt install docker-compose-plugin だけで V2 が利用可能になるため、追加のスクリプトは不要。
CI のログにバージョン情報を出すことで、環境差異が原因の失敗を防止できる。

4‑3. GitLab CI（Alpine ベース）実装例

stages:
  - build
  - test

variables:
  DOCKER_HOST: &quot;tcp://docker:2375&quot;
  COMPOSE_DOCKER_CLI_BUILD: &quot;1&quot;

services:
  - docker:dind   # Docker-in-Docker を使用

build:
  stage: build
  image: docker:23.0.6   # Docker CLI が入った公式イメージ
  script:
    # Alpine に compose plugin をインストール（apk パッケージは community リポジトリにあります）
    - apk add --no-cache docker-compose-plugin

    - docker compose version      # バージョン確認
    - docker compose build --pull
    - docker compose up -d
  cache:
    key: &quot;$CI_COMMIT_REF_SLUG&quot;
    paths:
      - .docker/cache/

stages:

- build

- test

variables:

DOCKER_HOST: "tcp://docker:2375"

COMPOSE_DOCKER_CLI_BUILD: "1"

services:

- docker:dind # Docker-in-Docker を使用

build:

stage: build

image: docker:23.0.6 # Docker CLI が入った公式イメージ

script:

# Alpine に compose plugin をインストール（apk パッケージは community リポジトリにあります）

- apk add --no-cache docker-compose-plugin

- docker compose version # バージョン確認

- docker compose build --pull

- docker compose up -d

cache:

key: "$CI_COMMIT_REF_SLUG"

paths:

- .docker/cache/

ベストプラクティス

キャッシュの活用
docker compose build のレイヤーは --cache-from と組み合わせ、.docker/cache/ に保存すれば次ジョブで再利用可能。
権限設定
GitLab Runner が Docker デーモンにアクセスできるよう、DOCKER_HOST と docker:dind の組み合わせは必須。
プラグインのバージョン固定（必要に応じて）
yaml

apk add --no-cache docker-compose-plugin=2.23.0-r0
→ 予期しないメジャーアップデートによる破壊的変更を防止。

4‑4. セキュリティ上の留意点

項目	推奨設定
最小権限	CI ランナーは `docker` グループに所属させ、`root` 権限で実行しない。
イメージ署名	`docker compose pull --quiet` 前に Notary / Cosign でイメージの署名検証を実施。
ネットワーク分離	CI 内部用のブリッジネットワークは外部と切り離し、ポート公開は最小限に抑える。

5. トラブルシューティングとロールバックガイド

5‑1. よくあるエラーと対処法

エラーメッセージ	想定原因	解決策
`docker: error while loading shared libraries: libcompose.so`	`/usr/lib/docker/cli-plugins/` にバイナリが無い、または権限不足	`sudo apt-get install -y docker-compose-plugin` もしくは公式スクリプトで手動配置し、実行権限 (`chmod +x`) を付与
`docker compose: command not found`	PATH に `/usr/lib/docker/cli-plugins` が含まれていない	`/etc/profile.d/docker-cli.sh` に `export PATH=$PATH:/usr/lib/docker/cli-plugins` を追記し、シェルを再起動
`failed to create network bridge: address already in use`	同名ブリッジネットワークが既に存在	`docker network rm <name>` で削除、または Compose ファイル側で別名に変更

5‑2. 旧バージョン（Compose V1）との競合解消手順

# (1) 既存の docker-compose バイナリを確認
which docker-compose   # 例: /usr/local/bin/docker-compose

# (2) バックアップ取得（すでに実施済みならスキップ）
sudo mv /usr/local/bin/docker-compose /usr/local/bin/docker-compose.v1.bak

# (3) V2 用シンボリックリンクを再作成
sudo ln -sf /usr/lib/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose

# (4) 競合プラグインが残っていないか確認
docker compose version   # 正常にバージョン表示されれば完了

# (1) 既存の docker-compose バイナリを確認

which docker-compose # 例: /usr/local/bin/docker-compose

# (2) バックアップ取得（すでに実施済みならスキップ）

sudo mv /usr/local/bin/docker-compose /usr/local/bin/docker-compose.v1.bak

# (3) V2 用シンボリックリンクを再作成

sudo ln -sf /usr/lib/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose

# (4) 競合プラグインが残っていないか確認

docker compose version # 正常にバージョン表示されれば完了

5‑3. ネットワークモード変更時の注意点

network_mode: host を使用するサービスは、ホスト側で同名ネットワークが存在しないことを必ず確認。
V2 の docker compose up はデフォルトで bridge モードを生成しますが、host に変更すると権限エラー (permission denied) が出やすいため、CI 環境では privileged: true と併用しないこと。

5‑4. ロールバック手順（V2 → V1）

# 1&#xfe0f;&#x20e3; V1 バイナリを復元
sudo cp /usr/local/bin/docker-compose.v1.bak /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 2&#xfe0f;&#x20e3; 互換モードを有効化（必要に応じて）
export COMPOSE_COMPATIBILITY=1   # 一時的に有効
echo 'export COMPOSE_COMPATIBILITY=1' &gt;&gt; ~/.bashrc   # 永続化

# 3&#xfe0f;&#x20e3; 動作確認
docker-compose version    # V1 のバージョンが表示されれば完了

# 1️⃣ V1 バイナリを復元

sudo cp /usr/local/bin/docker-compose.v1.bak /usr/local/bin/docker-compose

sudo chmod +x /usr/local/bin/docker-compose

# 2️⃣ 互換モードを有効化（必要に応じて）

export COMPOSE_COMPATIBILITY=1 # 一時的に有効

echo 'export COMPOSE_COMPATIBILITY=1' >> ~/.bashrc # 永続化

# 3️⃣ 動作確認

docker-compose version # V1 のバージョンが表示されれば完了

復旧ポイント
- バイナリを上書きする前に必ずバックアップ (*.bak) を取得。
- 環境変数 COMPOSE_COMPATIBILITY は V1 が一部 V2 の構文を受け入れるためのフラグであり、CI スクリプトでも同様に設定可能。

6. 参考リンク・公式情報

項目	URL
Docker Engine インストールガイド	https://docs.docker.com/engine/install/
Docker Compose Plugin（公式）	https://docs.docker.com/compose/install/
GitHub Releases API（最新タグ取得例）	https://api.github.com/repos/docker/compose/releases/latest
Docker Buildx アクション（GitHub）	https://github.com/docker/setup-buildx-action
Docker Compose V2 リファレンス	https://docs.docker.com/compose/reference/

7. まとめ（最終チェックリスト）

OS と Docker Engine のバージョンが要件を満たすか確認
docker-compose-plugin を公式リポジトリ経由でインストール、もしくはスクリプトで最新版取得
シンボリックリンクまたは エイリアスで docker compose へ切り替え
docker compose version が期待通りに表示されることを検証
CI/CD パイプラインに同様の手順を組み込み、キャッシュと権限設定を最適化
障害が起きたら バックアップバイナリでロールバックし、COMPOSE_COMPATIBILITY=1 を活用

これらの手順を踏めば、Docker Compose V2 への移行は安全かつスムーズに完了します。実運用環境や CI ランナーでぜひお試しください。

スポンサードリンク

-Docker

comment コメントをキャンセル

: Docker

Dockerで開発スピード向上！イメージレイヤー・マルチステージ・Compose活用術

Dockerのイメージレイヤー、マルチステージビルド、Composeがキャッシュ活用・サイズ削減で開発サイクルを大幅に短縮します。

: Docker

Docker Desktop for Windows の対応OS・ハードウェア要件とインストール手順

Docker Desktop を Windows に導入するための OS・ハードウェア要件、WSL2 の有効化手順、公式インストーラ取得方法、GUI とサイレントインストールの具体的手順、よくあるエラーと対処法を網羅。

: Docker

Docker クライアントとデーモンの API バージョン不一致対策 – 2025‑2026 最新環境

Docker クライアントとデーモン間の API バージョン不整合によるエラーの原因と、バージョン確認・環境変数設定・Desktop 再起動・Engine アップグレード／ダウングレードの具体的手順をまとめました。

: Docker

DockerとCI/CDの基本と主要ツール別設定ガイド

DockerはCI/CDにおいて環境統一と再現性を保証し、主要ツール別の設定方法やセキュリティ対策まで網羅的に紹介します。

: Docker

Windows 11でDocker Desktopをインストールする手順と要件

Windows 11 Pro/Enterprise で Docker Desktop を安全に導入するためのシステム要件、WSL2 と Hyper‑V の有効化手順、インストールから初回設定・動作確認までを解説します。

Docker Desktopの無料利用条件と有償プランへの移行ガイド

Illustrator ver.29 パス上オブジェクトツールの新UIと使い方ガイド

Docker Compose V2 のインストールと移行ガイド【Linux対応】

1. 前提条件と対象 OS・Docker Engine バージョン

1‑1. 要点（冒頭にまとめ）

1‑2. サポート対象 Linux ディストリビューション

1‑3. Docker Engine バージョン別インストール要件

1‑4. 前提条件チェックリスト

2. Docker Compose V2 プラグインのインストール方法

2‑1. 要点

2‑2. apt / dnf によるインストール手順

Ubuntu / Debian（apt）

CentOS / Rocky Linux（dnf / yum）

2‑3. 公式インストールスクリプトによる手動配置

スクリプトのポイント

2‑4. インストール確認コマンド

3. 既存 docker‑compose から docker compose への移行手順

3‑1. 要点まとめ

3‑2. エイリアスとシンボリックリンクの比較

推奨手順（シンボリックリンク）

3‑3. docker-compose.yml の互換性と V2 推奨機能

基本的な互換性

新機能サンプル

3‑4. 移行後の検証フロー

4. CI/CD パイプラインへの適用とベストプラクティス

4‑1. 要点まとめ

4‑2. GitHub Actions（Ubuntu 22.04）実装例

4‑3. GitLab CI（Alpine ベース）実装例

4‑4. セキュリティ上の留意点

5. トラブルシューティングとロールバックガイド

5‑1. よくあるエラーと対処法

5‑2. 旧バージョン（Compose V1）との競合解消手順

5‑3. ネットワークモード変更時の注意点

5‑4. ロールバック手順（V2 → V1）

6. 参考リンク・公式情報

7. まとめ（最終チェックリスト）

3. 既存 `docker‑compose` から `docker compose` への移行手順

3‑3. `docker-compose.yml` の互換性と V2 推奨機能