Docker Tip #51: Which Docker Compose API Version Should You Use?
Docker Compose has 3 major API versions (v1, v2 and v3). Certain features are enabled / disabled depending on which one you use.
You have probably seen the version: '2' or version: '3' property at the top
of a docker-compose.yml file right?
Should You Ever Use v1 / Not Defining a Version?
Update in 2021: The new Docker Compose spec supports not defining a version property and is the recommended way to go moving forward. It supports both v2 and v3 properties. That makes this tip a little outdated but I’ve updated it a bit and will leave it around for historical purposes.
If you don’t see a version property at all that means 1 of 2 things depending
on what version of docker-compose you’re using. But the TL;DR takeaway is
since late 2020 (Docker Compose 1.27+) you shouldn’t define a version
property.
Between early 2016 (Docker Compose 1.6+) and late 2020 not defining a version
was considered legacy because v2 and v3 existed. Not defining a version was
classified as v1 back then and it didn’t support named volumes, networking or
custom build arguments.
Then in Docker Compose 1.27+, Docker deprecated the version property and it’s
mainly supported now for backwards compatibility. It supports everything
without it.
I covered this topic and more at DockerCon 21 in my Docker Compose best practices talk.
What about v2 or v3?
Update in 2021: This is the part I’m leaving around unedited for historical purposes.
A hard and fast rule would be to use the latest version, but you aren’t really
hurting yourself if you use an older version which is compatible with your
docker-compose.yml file.
Some of the major differences between v2 and v3 is that v3 does not support
using the volumes_from and extends properties. A whole bunch of the
CPU and memory properties have also been moved to a deploy property in v3
instead.
It’s also worth mentioning if you happen to be using Docker Swarm, you’ll need to use v3+.
A full list of what works with v2 and v3 can be found here.
What about the docker-compose Binary Version?
You should always update to the latest version whenever possible because it will likely contain bug fixes. You can view the compatibility matrix on Docker’s site to see if your API version is compatible with a specific binary version (they are separate things).