dockerdocker-compose

How to determine highest docker-compose file version for the installed docker-compose


I have docker-compose 1.25.4 on a system, and docker 19.03. How do I know which version of Compose file format it supports, without trying a bunch or searching through release notes etc?

I determined by trial and error that the highest Compose file format version that docker-compose 1.25.4 supports is 3.7. Therefore, my docker-compose.yml requires version: "3.7".

But what if I need to determine this programmatically? Or reliably, without trial and error, and without looking at release notes?

The docs at https://docs.docker.com/compose/compose-file/compose-versioning/ suggest that highest version should be 3.8 but this does not work. Indeed the release notes indicate that 3.8 became supported as of docker-compose 1.25.5.

I looked through various docker-compose commands and could not spot anything that would say "This version of docker-compose supports Compose file version up to x.y".

Update July 2025:

The compose schema version is no longer needed since compose v2. Per the official docs:

Version two of the Docker Compose command-line binary was announced in 2020, is written in Go, and is invoked with docker compose. Compose v2 ignores the version top-level element in the compose.yaml file.

In fact, you will get a warning if your compose yaml states version:

$ docker compose version 
Docker Compose version v2.37.3

# if yaml has a version attribute:
$ docker compose ... 
... 
WARN[0000] /path/to/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion

Therefore this question only relates to pre-v2 compose (v2 came out in 2020, and v1 became officially deprecated in July 2023).


Solution

  • I figured out that there is no way to find this out via the cli. You need to check the docker-compose github releases for this.

    For example on Ubuntu: v1.25.0 version of docker-compose which is currently the latest and gets to be installed by default, but it is compatible with the 3.7 at highest. https://github.com/docker/compose/releases/tag/1.25.0

    The Compose file format compatibility matrix part is the interesting here.