What does the first line in the "docker-compose.yml" file, that specifies the version mean?
May 2
In the first line of the docker-compose.yml file we specify a version:
version: '3.9'
What exactly does this mean?!
After installing the latest version, I tried the following in my Windows 10 cmd:
docker-compose --version
and the output was:
Docker Compose version v2.17.2
so how is it that we type 3.9 in the first line?!
docker1 answer
Accepted answer · original discussion
May 2
That specific line means you are using the new plugin version of Compose that ignores the version: line.
Historically there were two different implementations of the Compose tool, one written in Python (docker-compose with a hyphen) and one written in Go and distributed as a Docker extension (docker compose with a space). Your output Docker Compose version v2... means you are using the newer Go-plugin version of Compose.
Separately, there are four different versions of the Compose file format:
| Version | version: |
Supports | Python Compose | Plugin Compose |
|---|---|---|---|---|
| 1 | Absent | Pre-Docker networks | Y | |
| 2 | 2, through 2.4 |
Single-host Docker | Y | Y |
| 3 | 3, through 3.8 |
Docker Swarm | Y | Y |
| Specification | Ignored | Plugin Compose only | Y |
In particular, see Compose file versions and upgrading: there was never a version: '3.9', which means the Python version of Compose will reject the file. The plugin version of Compose uses the Compose Specification format, which is mostly backwards-compatible with both the version 2 and 3 formats.
Versions 2 and 3 have some minor differences especially around resource constraints, where version 2 generally directly mirrors docker run options and version 3 has some options that are compatible with Swarm but are ignored if you aren't using it.
My personal practice has generally been to use version: '3.8', which is the most recent version of the file format that both Compose implementations support. If I need the resource constraints then I'll use version: '2.4' instead (I do not use Swarm). If I was going to write something that used a Compose Specification specific feature then I'd probably write version: '4' to indicate the difference, or version: '4.0+compose-2.20' for features that need a specific version of the Compose tool; my experience elsewhere has been that these kinds of version markers tend to be useful.
The Python version of Compose was officially desupported in June 2023, which in principle reduces the number of options in this matrix. In particular, this will mean the version: line is ignored always, and any file will be interpreted as per the Compose Specification and not one of the older file formats. Since the tool ignores version:, it also means there is no way to tell the tool that it needs to be upgraded to use newer features.
0 question comments
Use comments to ask for clarification. Post a solution as an answer.
No question comments on this page.