According to this table, the latest version is 3.8. However, lower down on the same page it uses Version: "3.9".
Where did 3.9 come from? I thought 3.8 is the latest?
1 Like
Have noticed the inconsistancy on Compose file version 3 reference | Docker Docs as well (which used to be shown as default content on Overview | Docker Docs as well).
The Docker Engine 20.10.0 release notes indicate following for the client (for swarm deployments):
The Docker Compose 1.27.1 release notes indicate following:
So it’s safe to say 3.9 is the latest v3.x version. Though, it might not be necessarily your best option…
Rule of thumb:
– for swarm deployments, you must use a v3.x version of the compose schema
– for single node docker-compose deployments, you are better of to use the lastest v2.x specification, which still is 2.4, unless you want to use secrets, which are only available in the v3 schema.
Docker-compose deployments will ignore all swarm specific configuration items in a v3 compose file. Many low level features available in v2 are missing in a v3 schema - or they moved underneath the swarm specific deploy configuration item, which gets igored for docker-compose deployments.
4 Likes
Do you know what features?
I don’t know all affected features from the top of my head.
What directly commes to mind are mainly cgroups oriented ressource contraints (limit ram, cpu, io). I know others are affected as well, but I would need to dig thru the docu to list them - forgive me If I am too lazy to do that 
. Actualy the docs for the v3 schema will indicate those config items and will recommend to switch to the v2 schema if those config items are required.
1 Like
Thanks. I see what you mean.
But this is even more confusing. This and this say that extends was removed from v3, however, I am using version: "3.9" in my Docker file and extends is working as expected…
Seems like you found another inconsistency
Maybe extends still work with docker-compose, but don’t with stack deployments (=swarm services)
That what’s left of my swarm deployments leverages make and simple envsubst substition to render the docker-compose.yml files before passing them to docker stack deploy -c - (=read compose file from STDIN). The same can be done with docker-compose using docker-compose -f -. I found it to provide more flexibility then working with any of the build in mechanisms.
Instead of envsubst, one could use gomplate and go wild with the template and add conditional blocks (expose ports for specific purpose? use database x instead of y, add n replicas instead of a single container, add service z to the mix… whatever commes to mind). Though what feels natural for Kubernetes deployments with helm charts (which pretty much bring this kind of templating to the table + versioning + simple way to override parameters from the cli) feels cumbersome for compose/swarm deployments.
1 Like
thanks, very informative!
Why haven’t the docs here (Compose file | Docker Documentation) been updated?
I assume because it’s not on the top priority list. After all the development and docu updates are done by volunteers. Seems like no one voluntered to update it so far. Everyone can actualy “edit the page”, which forkes the docu project on github. Once finished with the changes, a PR will put the changes on the radar of whoever is permitted to handle PR’s.
From what I remember correct schema version 3.9 extends the schema with a windows container related new feature.
Yeah, I know documentation is never a priority and its hard to do but it is important. Millions of people use Docker and if the documentation isn’t right it can create big problems for everyone. 
And then when enough folks have issues they stop using the product/tool.
Hopefully they get around to fixing it soon.