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?!
That specific line means you are using the new plugin version of Compose that ignores the version: line.
There are 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; my experience elsewhere has been that these kinds of version markers tend to be useful.
As of this writing in May 2023, Docker is planning to desupport the Python version of Compose by the end of June 2023, which will reduce 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.