Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Compose refuses the version line in docker-compose.yml

ErrorVersion in "./docker-compose.yml" is invalid.

Short answer

This error comes from the old Python docker-compose v1 tool. Its own message names two ways it happens: the version value is not one it supports, or the service definitions are not placed under a services key. Fix the layout, or switch to docker compose (v2), which ignores the version line.

  • Applies to Docker Compose v2, docker-compose v1, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check which tool you run. A hyphen means the old v1 binary; a space means the v2 plugin.

    docker-compose version
    docker compose version
  2. 2Match what you see, then jump to its fix

    1. 1The command is docker-compose (with a hyphen) and the file works on other machinesThe old docker-compose v1 binary is reading a newer fileFix
    2. 2The message suggests placing service definitions under the services key, or omitting versionServices are not under a services keyFix
    3. 3Version in "./docker-compose.yml" is invalidThe version value is malformedFix

What does the error look like?

  • Version in "./docker-compose.yml" is invalid.
  • You might be seeing this error because you're using the wrong Compose file version.
  • or omit the `version` key and place your service definitions at the root of the file to use version 1.

Cause 1 of 3

The old docker-compose v1 binary is reading a newer file

1Check

Compose v1 is the Python tool called with a hyphen. Compose v2 is a Go plugin called as docker compose. Only v2 treats the version key as optional.

docker-compose version
docker compose version

2Fix

Install the Compose plugin and run docker compose instead. On Ubuntu with Docker's apt repository the package is docker-compose-plugin. Remove the version line from the file, since v2 only warns that it is obsolete.

sudo apt install docker-compose-plugin
docker compose up -d

3Verify

docker compose version prints a v2 version and the stack starts.

docker compose version
docker compose config

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

Services are not under a services key

1Check

A file with version 2 or 3 must nest every service under services:. Without that key, the tool falls back to treating the file as the legacy version 1 layout.

head -n 12 docker-compose.yml

2Fix

Indent each service under a services: key. Keep the version line only if you must stay on v1.

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

3Verify

Compose parses the file and prints it back.

docker compose config

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

The version value is malformed

1Check

In v1 the value must be a quoted string like "3.8" that starts with 2 or 3. A non-string value raises an error, a dict falls back to version 1 with a warning, and a string starting with 1 is rejected.

grep -n '^version' docker-compose.yml

2Fix

Quote the value, or delete the line and use docker compose v2, where it is only informative.

version: "3.8"

3Verify

The file loads without the invalid version error.

docker compose config

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Use docker compose (v2) everywhere, in scripts and CI, not docker-compose.
  • Leave the version line out of new Compose files.
  • Keep one Compose command per team so files behave the same on every machine.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

A dev container port does not open in the browser when Docker runs on a remote host

If your application only accepts calls from localhost, it will reject connections from published ports

Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.