docker-compose.ymlのversionフィールド

<WARNING> **重要な最新情報 (2024年時点)** Docker公式ドキュメントで明示され、現代的なCompose環境では`version`の指定が**不要かつ非推奨**です。ファイルに記載すると警告が表示されます： ```bash WARNING: The top level 'version' key is obsolete and ignored. ``` </WARNING>

問題の本質

docker-compose.ymlの先頭行にあるversion: '3.9'のような記述は、コマンドdocker-compose --versionで確認されるツール自体のバージョン（例：v2.17.2）とは全く別の概念を示しています。多くのユーザーがこの不一致に混乱します。

混乱の具体例

bash

docker compose --version
# 出力: Docker Compose version v2.17.2

yaml

version: '3.9' # コマンド出力と値が異なる!
services:
  web:
    image: nginx

解決策：versionフィールドの正しい理解

核心的な解釈

versionフィールドはComposeファイルのスキーマバージョンを示す
Docker Composeツールの実行バージョンとは無関係
現在の推奨はこの行を完全に削除する

歴史的背景

Composeの進化に伴い異なるバージョン体系が存在しました：

ファイルバージョン	`version:` 値	特徴	対応Composeツール
1	(未指定)	Dockerネットワーク未対応	Python Composeのみ
2	`2` ～ `2.4`	単一ホスト向け機能	両対応
3	`3` ～ `3.8`	Docker Swarm対応	両対応
Compose仕様	不要 (非推奨)	モダンCompose機能	プラグイン版のみ

<TIP> **バージョン2.4/3.8が境界線** 2023年までは互換性のため`version: '3.8'`推奨されましたが、現在は推奨されません。 </TIP>

現在のベストプラクティス

versionフィールドを削除
最新のDocker Compose（v2以降）では記載は冗長です
diff
```
- version: '3.9'
services:
  app:
    image: my-app:latest
```
旧環境との互換性が必要な場合の対処法
レガシープロジェクトでは最小限の値を指定：
yaml
```
version: '3.8' # 最大互換性バージョン
```

使用ツールの確認
あなたのCompose実装を判別：

bash

# ハイフン有り → 旧Python版 (非推奨)
docker-compose --version

# スペース区切り → モダンなプラグイン版
docker compose --version

技術的な詳細解説

なぜversion指定が紛らわしいのか

かつて存在したdocker-compose（Python実装）はバージョン値で挙動を変更
現在主流のdocker compose（Goプラグイン）は値を無視する互換モード
公式が「Compose仕様」に統一したためversion分岐が無意味化

バージョンの役割終了理由

機能ロック回避
ファイルのversionで古い挙動に縛られる問題を解消
仕様と実装の分離
Composeファイルの解釈規則を独立して進化可能に
警告メッセージの目的
⚠️ ユーザーに不要な記述を気付かせるための設計

<CAUTION> **永続的互換性では無い** `version: '3.8'`のような旧フォーマット指定は、Composeによって将来のバージョンでサポートが廃止される可能性があります。 </CAUTION>

実用的アドバイス

新規プロジェクト
versionフィールドそのものを書かないことを推奨
既存プロジェクトの更新
機能に影響がなければversion行を安全に削除可能
警告が出力される場合
コンテナ動作に問題がなければ無視してOK

関連記事

docker-compose.ymlのversionフィールド ​

問題の本質 ​

混乱の具体例 ​

解決策：versionフィールドの正しい理解 ​

核心的な解釈 ​

歴史的背景 ​

現在のベストプラクティス ​

技術的な詳細解説 ​

なぜversion指定が紛らわしいのか ​

バージョンの役割終了理由 ​

実用的アドバイス ​