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).