How to fix ERROR: Version in './docker-compose.yml' is unsupported in Docker

First, determine which version of Docker Compose you have installed:

# Check the old standalone tool
docker-compose --version

# Check Docker Compose V2 (plugin)
docker compose version

Compare the output to the version in your docker-compose.yml. Common version support:

| docker-compose version | Max Compose file version |
|----------------------|-------------------------|
| 1.17.x | 3.4 |
| 1.18.x - 1.20.x | 3.5 |
| 1.21.x - 1.23.x | 3.6 |
| 1.24.x - 1.26.x | 3.7 |
| 1.27.x+ | 3.8 |
| V2 (docker compose) | No version required |

If you're using Docker Compose V2, you should see output like Docker Compose version v2.x.x.

If you're using Docker Compose V2 (the modern docker compose plugin), simply remove the version: line from your docker-compose.yml:

Before:

version: "3.8"
services:
  web:
    image: nginx

After:

services:
  web:
    image: nginx

Starting with Compose V2, the version field is obsolete. Docker now uses the most recent schema automatically and validates your file based on what features you actually use.

After removing the version line, run:

docker compose up

Note the space between docker and compose - this is the V2 syntax.

If you need to support the version field or prefer using the older syntax, upgrade Docker Compose:

On Linux (install V2 as plugin):

# Remove old standalone docker-compose
sudo apt-get remove docker-compose

# Install Docker Compose plugin (V2)
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Verify installation
docker compose version

Alternative: Install latest standalone docker-compose:

# Download latest version
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# Make executable
sudo chmod +x /usr/local/bin/docker-compose

# Clear shell cache
hash -r

# Verify
docker-compose --version

On macOS/Windows:
Update Docker Desktop to the latest version. Docker Compose V2 is included.

If you cannot upgrade Docker Compose, lower the version in your Compose file to match what your installation supports:

# Change from unsupported version
version: "3.8"

# To a supported version (check your docker-compose version)
version: "3.4"

Common safe version choices:
- version: "3" - Equivalent to 3.0, works with most installations
- version: "2.4" - Stable, good for development (has depends_on with healthcheck)
- version: "3.4" - Works with docker-compose 1.17+

Note: Lowering the version may disable features you're using. Check the [Compose file version differences](https://docs.docker.com/compose/compose-file/compose-versioning/) to understand what features each version supports.

The version field is sensitive to formatting. Ensure you're using standard double quotes:

Wrong - Smart quotes (from copy-paste):

version: "3.8"  # These are curly/smart quotes

Wrong - Missing quotes:

version: 3.8  # Will be parsed as float, not string

Correct:

version: "3.8"  # Standard double quotes
version: '3.8'  # Single quotes also work

To find hidden characters, check your file in a hex editor or run:

cat -A docker-compose.yml | head -5

If you see unusual characters around the quotes, retype the line manually.

If you have both old docker-compose and new Docker Compose V2 installed, switch to the new command:

# Old command (standalone python tool - deprecated)
docker-compose up

# New command (Docker plugin - recommended)
docker compose up

Docker Compose V2 is built into Docker and handles version fields more gracefully. It will accept any valid version string and automatically use the latest features available.

To check if V2 is available:

docker compose version

If you see version 2.x output, you have V2 installed and should use docker compose going forward.

After upgrading docker-compose, your shell might still point to the old binary. Clear the cache:

# Bash/Zsh
hash -r

# Or specifically for docker-compose
hash -d docker-compose

Then verify you're using the new version:

which docker-compose
docker-compose --version

If the old version still appears, check your PATH for multiple installations:

# Find all docker-compose binaries
which -a docker-compose

# Or search common locations
ls -la /usr/local/bin/docker-compose /usr/bin/docker-compose 2>/dev/null

Remove or rename any old binaries that appear before the new one in your PATH.