Compose File version Key

Problem Statement

When creating a docker-compose.yml file, you'll often see the first line specifying a version like:

version: '3.9'

This frequently creates confusion when you check your Docker Compose tool version and get a completely different result:

docker-compose --version
# Output: Docker Compose version v2.17.2

Why are these version numbers different, and what purpose does the version key serve in the Compose file?

Understanding the Version Key

Historical Context

The version key defines the Compose file format specification, not the Docker Compose tool version. Two main implementations exist:

1. Legacy Python tool (docker-compose): The original implementation (requires version key)
2. Plugin for Docker CLI (docker compose): The modern implementation bundled with Docker Desktop

<warning> The legacy Python tool was officially desupported in June 2023. Use `docker compose` (with space) instead. </warning>

File Format Evolution

Version	version: Key	Purpose	Python Tool	Plugin Tool
1	Absent	Pre-Docker networks	✓	✗
2.x	'2.0'-'2.4'	Single-host Docker features	✓	✓
3.x	'3.0'-'3.8'	Docker Swarm compatibility	✓	✓
Specification	Ignored	Modern features (multi-platform)	✗	✓

Key Differences Between Formats

• Version 2.x: Adds native networking and volumes
• Version 3.x: Adds Docker Swarm mode compatibility
• Specification: Latest features with forward compatibility

Current Best Practice: Omit the Version Key

# Modern approach (omit version)
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"

<tip> Recent Docker versions treat all files as Compose Specification regardless of whether the `version` appears. </tip>

Modern Docker versions (plugin tool) generate a warning when the version key is present:

WARNING: The "version" key in your docker-compose.yml file is obsolete. Omit it to silence this warning.

Why Version 3.9 Is Problematic

The version: '3.9' specification never existed. This causes:

• Rejection by the legacy Python tool
• Warning in modern Docker (but file still processes)
• Compatibility uncertainty

Explanation of Tool Behavior

Comparing Tool Outputs

# Legacy Python tool (hyphen)
$ docker-compose --version
docker-compose version 1.29.2, build unknown

# Modern plugin version (space)
$ docker compose --version
Docker Compose version v2.17.2

When You Should Use a Version

Only include a version if:

1. Supporting systems running older Docker engine
2. Using features specific to a format
3. Maintaining compatibility with Swarm mode

Use maximum compatible version:

version: '3.8'  # Compatible with both tools

Recommendations

1. Upgrade to latest Docker Engine and docker compose plugin
2. Remove version key from new projects
3. For existing files:
   • Keep version if using features exclusive to v2/v3
   • Migrate to omission pattern when possible
4. Validate files using official syntax checker:

   docker compose config

Conclusion

The version key in docker-compose.yml files defined the file specification version. With the deprecation of the legacy Python tool and adoption of the Compose Specification, the version key has become obsolete. Modern Docker implementations process Compose files based on the current specification regardless of the specified version. For new projects, omit the version key. For existing projects, migrate to the version-less format when possible and validate configuration compatibility using docker compose config.