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

DockerBEGINNERLOWUpdated Dec 6, 2025· 265 views

The 'Version in docker-compose.yml is unsupported' error occurs when your Docker Compose file specifies a version number that your installed docker-compose tool doesn't recognize. This is typically resolved by upgrading Docker Compose, removing the version field entirely (for Compose V2), or lowering the version number.

Quick fix

Fixes ERROR: Version in './docker-compose.yml' is unsupported

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

# Check Docker Compose V2 (plugin)
docker compose version
  1. Check your Docker Compose version
  2. Remove the version field (recommended for Compose V2)
  3. Upgrade Docker Compose
  4. Lower the version number in docker-compose.yml
docker — error
# Check the old standalone tool
docker-compose --version
# Check Docker Compose V2 (plugin)
docker compose version
ERROR: Version in './docker-compose.yml' is unsupported

What this error means

The "Version in docker-compose.yml is unsupported" error indicates a mismatch between the `version:` field in your Compose file and what your installed Docker Compose understands. Docker Compose files historically required a `version:` declaration at the top (like `version: "3.8"`) to specify which features the file uses. Different versions of the docker-compose tool support different version ranges: - docker-compose 1.17.x supports up to version 3.4 - docker-compose 1.18.x supports version 3.5 - docker-compose 1.24.x supports version 3.7 - docker-compose 1.27+ supports version 3.8 **Important change**: Starting with Docker Compose V2 (the `docker compose` command without the hyphen), the `version:` field is now obsolete. Compose V2 automatically uses the latest schema and ignores the version field - in fact, including it triggers a deprecation warning. This error most commonly appears when: 1. You're using an older docker-compose installation that doesn't support newer version numbers 2. Your Compose file specifies a version that doesn't exist (like "3.9" in some older docs) 3. There's a syntax issue with the version field itself

Typical symptoms

  • Running `docker-compose up` shows 'Version in ./docker-compose.yml is unsupported'
  • The error mentions 'You might be seeing this error because you're using the wrong Compose file version'
  • Compose commands fail immediately without starting any containers
  • CI/CD pipelines fail at the docker-compose step
  • The same docker-compose.yml file works on other machines but not yours
  • Error appears after copying a docker-compose.yml from a tutorial or GitHub project

Common causes

  1. Outdated docker-compose installation that doesn't support the specified version (most common)
  2. Compose file specifies a version number higher than your docker-compose supports
  3. Using the old `docker-compose` command instead of the new `docker compose` (V2)
  4. Typographical error in the version field (wrong quotes, extra characters)
  5. Compose file references a non-existent version like '3.9' from outdated documentation
  6. Shell caching pointing to an old docker-compose binary after upgrade

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

1Check your Docker Compose version

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

bash
# 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.

2Remove the version field (recommended for Compose V2)

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

Before:

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

After:

yaml
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:

bash
docker compose up

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

3Upgrade Docker Compose

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

On Linux (install V2 as plugin):

bash
# 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:

bash
# 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.

4Lower the version number in docker-compose.yml

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

yaml
# 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.

5Fix version field syntax issues

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

Wrong - Smart quotes (from copy-paste):

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

Wrong - Missing quotes:

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

Correct:

yaml
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:

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

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

6Use the new docker compose command

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

bash
# 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:

bash
docker compose version

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

7Clear shell hash cache after upgrading

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

bash
# Bash/Zsh
hash -r

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

Then verify you're using the new version:

bash
which docker-compose
docker-compose --version

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

bash
# 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.

Advanced notes

### Understanding Compose File Versions

The version: field in docker-compose.yml evolved through several generations:

Version 1 (legacy): No version field. Simple key-value syntax without services block.

Version 2.x: Introduced services:, networks:, volumes: top-level keys. Added features like depends_on with health checks.

Version 3.x: Designed for Docker Swarm compatibility. Some version 2 features (like resource limits in non-swarm mode) were changed.

Compose Specification (current): The version field is obsolete. Docker Compose V2 uses the Compose Specification which is versioned separately from the tool.

### Compose V2 Migration

Docker deprecated the standalone docker-compose Python tool in favor of docker compose (a Go-based plugin). Key differences:

| Feature | docker-compose (V1) | docker compose (V2) |
|---------|--------------------|--------------------|
| Version field | Required | Optional (obsolete) |
| Command | docker-compose | docker compose |
| Install | Separate | Included with Docker |
| Language | Python | Go |

### CI/CD Considerations

In CI/CD pipelines, you may encounter this error due to different docker-compose versions across environments. Solutions:

1. Pin the version: Install a specific docker-compose version in your CI config
2. Remove version field: Use versionless Compose files with docker compose
3. Use lowest common version: Specify a version all environments support

Example GitHub Actions workflow:

yaml
- name: Setup Docker Compose
  run: |
    docker compose version || \
    (curl -L "https://github.com/docker/compose/releases/download/v2.24.0/docker-compose-linux-x86_64" -o /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose)

### The "3.9" Version Myth

Some older documentation references version: "3.9", but this version was never officially released for the original Compose file format. If you see this in a tutorial, use version: "3.8" or remove the version field entirely when using Compose V2.

### Compatibility Matrix

For reference, here's the Docker Engine requirement for each Compose file version:

| Compose file version | Docker Engine |
|---------------------|---------------|
| 3.8 | 19.03.0+ |
| 3.7 | 18.06.0+ |
| 3.6 | 18.02.0+ |
| 3.5 | 17.12.0+ |
| 3.4 | 17.09.0+ |
| 3.3 | 17.06.0+ |
| 2.4 | 17.12.0+ |

Frequently asked questions

What does "ERROR: Version in './docker-compose.yml' is unsupported" mean?
yml is unsupported" error indicates a mismatch between the version: field in your Compose file and what your installed Docker Compose understands. 8") to specify which features the file uses. 8 Important change: Starting with Docker Compose V2 (the docker compose command without the hyphen), the version: field is now obsolete.
How do I fix "ERROR: Version in './docker-compose.yml' is unsupported"?
The 'Version in docker-compose.yml is unsupported' error occurs when your Docker Compose file specifies a version number that your installed docker-compose tool doesn't recognize. This is typically resolved by upgrading Docker Compose, removing the version field entirely (for Compose V2), or lowering the version number.
What causes "ERROR: Version in './docker-compose.yml' is unsupported"?
Outdated docker-compose installation that doesn't support the specified version (most common) Compose file specifies a version number higher than your docker-compose supports Using the old docker-compose command instead of the new docker compose (V2)
Is the "ERROR: Version in './docker-compose.yml' is unsupported" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading