Docker Compose error: Version in docker-compose.yml is unsupported

Verified FixPython 3.10+Docker Compose V2 / Compose SpecSilo: devops

Quick Fix / Solution Rapide

Remove the top-level version: '3.8' line from your docker-compose.yml file; modern Docker Compose V2 automatically follows the latest Compose Specification.

Root Cause Analysis

This error occurs when running modern Docker Compose V2 (docker compose) against a docker-compose.yml file containing an obsolete or unsupported version: header attribute (such as version: '3.9' or version: '2.4').

1. The Compose File Specification Unification

In legacy Docker Compose V1 (docker-compose Python tool), developers had to declare version: '3.8' or version: '2' to specify feature sets. Under the modern Docker Compose Specification and Docker Compose V2 (Go-based CLI plugin), the top-level version attribute was deprecated and declared obsolete.

2. Deprecation Warnings and Strict Parser Validation

Modern Docker tools issue warnings or errors when encountering outdated version declarations that conflict with unified Compose features.

3. Unsupported Version String Numbers

Specifying non-existent or unsupported version strings (e.g. version: '4.0') causes parser validation failure.

4. Toolchain Version Mismatch (Compose V1 vs V2)

Mixing old CI/CD scripts calling legacy docker-compose with modern Docker engines.

Reproduction Code (MCVE)

Example: Bug Reproduction

import yaml

sample_yaml = '''
version: '3.8'
services:
  web:
    image: python:3.12-slim
'''

def validate_compose_v2_spec(content):
    data = yaml.safe_load(content)
    if 'version' in data:
        raise ValueError(f"Version in docker-compose.yml is unsupported: top-level attribute 'version: {data['version']}' is obsolete in Compose V2 specification.")

validate_compose_v2_spec(sample_yaml)

Solution 1: Remove the Obsolete version: Line from docker-compose.yml

Delete the top-level version line; Docker Compose V2 starts directly with services:.

Example: Recommended Solution

import yaml

# Modern Compose Spec format
clean_yaml = '''
services:
  web:
    image: python:3.12-slim
    ports:
      - "8000:8000"
'''
data = yaml.safe_load(clean_yaml)
print(f'Valid modern Compose configuration with services: {list(data["services"].keys())}')

Solution 2: Upgrade CI/CD to docker compose (V2)

Replace legacy docker-compose commands with modern Docker CLI plugin docker compose in automated build scripts.

Example: Alternative Solution

print('Modern CLI command (V2):')
print('docker compose up -d')
print('docker compose build')

A common mistake is worrying that removing version: breaks compatibility. Docker Compose V2 was designed specifically to infer all capabilities without a version string. Edge cases occur with legacy Swarm deployments: Docker Stack deploy still reads version 3.x strings; for standard Docker Compose workflows, omit the version. Contrast this error with yaml.scanner.ScannerError, which occurs when YAML indentation is malformed.

Previous Next