Compose refuses the version line in docker-compose.yml
Version 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.
Fix it fast
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 version2Match what you see, then jump to its fix
- 1
The 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
The message suggests placing service definitions under the services key, or omitting versionServices are not under a services keyFix - 3
Version in "./docker-compose.yml" is invalidThe version value is malformedFix
- 1
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 version2Fix
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 -d3Verify
docker compose version prints a v2 version and the stack starts.
docker compose version
docker compose configConfirmed by docs.docker.com
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.yml2Fix
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 configConfirmed by raw.githubusercontent.com
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.yml2Fix
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 configConfirmed by raw.githubusercontent.com
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
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
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