docker compose と docker-compose の違い

問題

Docker Compose を使う際に、docker-compose（ハイフン付き）と docker compose（スペース区切り）の2種類のコマンドが存在することに気づくことがあります。これらの違いについて理解することは、効率的なDocker運用のために重要です。

注意

この記事は歴史的な経緯も含めて解説しますが、現在では docker compose（v2）が公式に推奨されるバージョンです。

歴史的背景

docker-compose (v1)

• 開発言語: Pythonで書かれた外部ツール
• 歴史: 元々は複数コンテナの管理を目的として開発され、fig.ymlという設定ファイルを使用していました
• 進化: 後にDocker Desktopに組み込まれ、設定ファイルは compose.yml → docker-compose.yml と名称変更されました

docker compose (v2)

• 開発言語: Go言語で書き直され、Docker CLIのプラグインとして実装
• 特徴: Dockerコマンドのサブコマンドとして統合
• 設定ファイル: compose.ymlが再度推奨されるようになりました

主な違い

1. コマンド形式

# v1 (旧式)
docker-compose up

# v2 (推奨)
docker compose up

2. イメージタグの命名規則

v1とv2では、ビルド時のイメージタグ生成方法が異なります：

# compose.yml
services:
  web:
    build: ./webapp

プロジェクトディレクトリが my_proj の場合：

v1: アンダースコア区切り

docker-compose build web
# 生成されるイメージ: my_proj_web

v2: ハイフン区切り

docker compose build web  
# 生成されるイメージ: my_proj-web

3. 環境変数ファイルの読み込み場所

マルチ環境設定における .env ファイルの扱いが異なります：

# docker-compose.yml
services:
  wordpress:
    image: wordpress
    env_file:
      - ${PWD}/.env  # パスの解決方法がv1とv2で異なる

• v1: 現在の作業ディレクトリの .env を読み込み
• v2: Composeファイルがあるディレクトリの .env を読み込み

インストール方法

Linuxでのdocker compose (v2) インストール

aptを使用

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

手動インストール

mkdir -p ~/.docker/cli-plugins/
curl -SL https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

最新版を自動取得

DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

docker-compose (v1) を維持したい場合

# v1を手動インストール
sudo curl -SL https://github.com/docker/compose/releases/download/v1.29.2/docker-compose-Linux-x86_64 -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

設定ファイルの互換性

サポートされるファイル名

Composeは以下の設定ファイル名を認識します（優先順位順）：

1. compose.yml
2. compose.yaml
3. docker-compose.yml
4. docker-compose.yaml

推奨

新しいプロジェクトでは compose.yml を使用し、従来の docker-compose.yml からの移行を検討してください。

設定バージョンの変更点

v2では以下のような変更が行われています：

• ネットワーク解決: /etc/hosts の直接更新から内部DNSリゾルバー（127.0.0.11）を使用する方式に変更
• 機能の削除: 設定バージョン3で extends キーなどの機能が削除されました
• 互換性: 大半のv1機能はv2でもサポートされています

移行時の注意点

環境変数の取り扱い

複数の独立した環境を単一ホストで運用する場合、プロジェクトディレクトリの扱いが異なります：

# v1とv2でプロジェクトディレクトリの決定方法が異なる可能性があります
docker --project-directory /path/to/project compose up

スクリプトの修正

既存のスクリプトで docker-compose を使用している場合：

# スクリプト内の変更例
# 従来: docker-compose up -d
# 変更後: docker compose up -d

重要

本番環境で移行する前に、開発環境で十分なテストを行ってください。

推奨事項

1. 新規プロジェクト: docker compose (v2) を使用する
2. 既存プロジェクト: 段階的な移行を検討する
3. 互換性問題: イメージタグの命名規則や環境変数の解決方法の違いに注意する
4. 設定ファイル: compose.yml 形式への移行を推奨

トラブルシューティング

バージョン確認

現在使用しているComposeのバージョンを確認：

# v2のバージョン確認
docker compose version

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

互換性問題への対応

もしv2で問題が発生した場合：

1. 一時的にv1を使用する
2. Docker ComposeのIssueトラッカーで既知の問題を確認する
3. 設定ファイルを調整する

結論

docker-compose (v1) から docker compose (v2) への移行は、Dockerプラットフォームの統合性を高める重要なステップです。新しいプロジェクトではv2を採用し、既存プロジェクトは計画的な移行を目指すことが推奨されます。両者の細かい違いを理解し、テスト環境で十分な検証を行うことで、シームレスな移行が可能になります。

最新情報は公式ドキュメントで常に確認することをお勧めします。