Fix 'Version in docker-compose.yml is unsupported' in Compose

What this error means

The message ERROR: Version in "docker-compose.yml" is unsupported appears when your Compose binary cannot parse the version declared in the file. This typically happens when:

• You are using legacy docker-compose (Compose V1) that doesn’t understand version values like "3.8" or "3.9".
• You’re mixing Compose V1/V2 behaviors. Compose V2 (docker compose) follows the Compose Specification and does not require a version field at all.

In most modern setups, removing the version: line or upgrading to Compose V2 fixes the issue.

Quickstart (fastest fix)

1. Identify which Compose you are using:
   • docker compose version → Compose V2
   • docker-compose version → Compose V1 (deprecated)
2. If you are on Compose V2, remove the version: line from your docker-compose.yml.
3. Validate: docker compose config
4. Start: docker compose up -d
5. If you are on legacy docker-compose (V1), either switch to docker compose (recommended) or change version to a lower known value (e.g., '3.7'). Upgrading is safer and future-proof.

Minimal working example (no version field)

Use this file as docker-compose.yml. It works with Compose V2 without version:.

docker-compose: false
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

Run it:

# Bring services up in the background
docker compose up -d

# Validate/inspect the composed config
docker compose config

# Check running containers
docker ps --filter "name=web"

If you must use legacy docker-compose, try adding a compatible version line:

version: "3.7"
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

Step-by-step diagnosis and fixes

1. Check your Compose flavor

   • docker compose version → shows Docker Compose version v2.x.y (plugin)
   • docker-compose version → shows docker-compose version x.y.z (V1)
   • Prefer V2: use docker compose ... (space, no hyphen)

2. Remove or adjust the version field

   • Compose V2: Delete the version: line entirely; it’s not required and is ignored by the Compose Specification.
   • Compose V1: If you cannot upgrade, pick a supported version (often "3.7" or lower). Newer values like "3.8"/"3.9" can trigger the error on older binaries.

3. Upgrade to Compose V2 (recommended)

   • Docker Desktop (Windows/macOS): update Docker Desktop; it includes Compose V2.
   • Linux: install the compose plugin, then prefer docker compose.
     • Example (Debian/Ubuntu):
       • sudo apt-get update && sudo apt-get install -y docker-compose-plugin
   • Optionally remove legacy V1 shim if present:
     • sudo rm -f /usr/local/bin/docker-compose

4. Validate before running

   • docker compose config → renders the merged, canonical configuration and validates the schema.
   • docker compose ls / ps → confirm projects and containers.

5. Try again

   • docker compose up -d
   • If the error persists, ensure you’re actually invoking the V2 plugin (docker compose ...), not the V1 binary.

Common causes and exact fixes

Pitfalls to avoid

• Keeping version: in Compose V2: It’s ignored and can confuse teams. Remove it.
• Assuming deploy: works outside Swarm: In Compose (non-Swarm), deploy: is ignored.
• Wrong file selected: docker compose looks for compose.yaml|compose.yml|docker-compose.yml|docker-compose.yaml. Use -f to be explicit if needed.
• YAML indentation/format errors: The error may mask basic YAML mistakes. Validate with docker compose config.
• Mixing commands: docker-compose and docker compose have different behaviors; use only one (prefer V2).

Performance and workflow notes

• Prefer Compose V2 for faster, parallel pulls/builds and better caching behavior.
• Validate frequently: docker compose config catches schema and interpolation issues early.
• Start only what you need: use --no-deps, --profile, or target specific services to reduce startup time.
• Pre-pull images: docker compose pull to avoid build/pull delays during up.
• Use bind mounts for rapid iteration in dev; switch to multi-stage builds and named volumes for production-like runs.

Why removing version works

Compose V2 implements the Compose Specification, which does not require a version tag. The spec evolves without breaking changes by default. Omitting version tells the tool to apply the latest spec it supports, avoiding mismatches between file and binary.

Tiny FAQ

• Do I need version: in Compose files?

  • No. With docker compose (V2), omit it.

• I must stay on docker-compose (V1). What version should I use?

  • Try version: "3.7". If that fails, use a lower value or upgrade to V2.

• Is docker-compose deprecated?

  • Yes. The V1 Python-based binary is deprecated. Use the V2 plugin: docker compose.

• Does the file name matter?

  • Compose V2 auto-detects compose.yaml, compose.yml, docker-compose.yml, and docker-compose.yaml. You can also pass -f.

• How can I confirm my file is valid?

  • Run docker compose config. If it succeeds, your file is structurally correct.