STOP versioning your Docker Compose file

Docker Compose is one of the best inventions, it makes local development easy and friction-free. If you are a long-term Docker Compose fanatic like me, you know we have come a long way. Currently, we are using version 2 of Compose, which is written in Golang. Version 1 of Compose was written in Python and has been deprecated. The last update was on May 10, 2021. Since then, the packages haven't received any security updates and it's not recommended to use it due to security reasons. You can read more about Compose history here.

Image credit: Docker docs

This was not just a change in the programming language from Python to Golang. A lot of things changed during this transition, from the command to run it to how we structure our compose files.

For instance, to trigger the binary for Compose v1, we used docker-compose up or docker-compose down, etc., because previously, we had installed the binary separately. Now, it's docker compose up with no dash - between 'docker' and 'compose' because Compose now comes pre-installed with Docker as a subcommand (if you are using Docker for Desktop). This was the most visually different change anyone could notice.

But, there is one more big change: no further need to version the compose file like we used to do. Interestingly, a lot of people didn't pay attention to this (including me), as the compose file with a version was still compatible. Also, I think the messaging was not strong enough to remove the version when people were migrating from v1 to v2, and is the whole purpose of this blog to make people aware.

Now, Docker is more active in getting this version form out of compose files by giving you a warning in the terminal.

At this point, it's just a warning, not an error, because the majority of people are still using versions, and changing this at once by throwing an error can lead to breaking a lot of apps.

If you don't believe me, I searched on GitHub and found around a MILLION projects (usually it's one compose file per project) still use versions in their compose files.

Btw, here is one more tip, if you still using the old convention of naming a compose file - docker-compose.yaml, start using compose.yaml.

That's it for this blog. I hope you enjoyed this style of writing, which is more like short storytelling and freestyle. I'm glad you're still reading and made it to the end—thank you so much for your support. Before you go, I want to share that I was recently recognized as a Docker Captain. You can check out the announcement post here.

Comments

[Denys Bochko]

Never knew that, I use docker-compose a lot, but I never thought of reading that fact.

At first, I thought you meant "source controlling" when you said versioning, but then I realized it's about that first line in the file. thanks, will take it to my projects.

[TheIceSentinel]

Second this. Maybe change it to "Stop using version in your docker compose" so it's more clear. Of course, clicks might be the point, but this is good to know. Will use on projects also.

[Pradumna Saraf]

Thank you, Thelce.

No, it was not about clicks :). This was the only title that first came to my mind. I didn't think of Git

[Denys Bochko]

I can understand how that came to your mind. The title suggested by TheIceSentinel would have worked for me in terms of clarity and I would still read the article since I use docker-compose.

I shared the knowledge in another article on this site the same day.

[Pradumna Saraf]

Thank you, Denys.

[Raphaël Louvradoux]

I third this :). I opened this post for the exact same reason then understood that you were talking about something that I was aware of 👌

[Chris Cook]

I’m not an expert on Docker, but the difference between using docker-compose with dash and docker compose without dash, seems to depend if you’re using the Compose standalone version vs the plugin.

Compose standalone
Note that Compose standalone uses the -compose syntax instead of the current standard syntax compose.
For example type docker-compose up when using Compose standalone, instead of docker compose up.
docs.docker.com/compose/install/st...

[Pradumna Saraf]

Thanks for pointing it out Chris. I should have made it clearer. I have fixed that

[Shrijal Acharya]

Now, Docker is more active in getting this version form out of compose files by giving you a warning in the terminal.

Wow, I've never noticed this warning pop up on my terminal before. When did they start adding it?

[Pradumna Saraf]

Thanks. Recently, a couple of weeks ago.

[Hylke de Vries]

I knew about the version line and the command change, since our last rewrite of our dev environment. But not about the file name. Since when is this different? And does it too have benefits?

[Pradumna Saraf]

Thank you. They have changed a long time ago. I think the Docker team didn't promote that much about it.

[Hassan]

Found useful, thanks!

[Pradumna Saraf]

Glad. Thank you, Hassan

[avelops]

Could have been more straight forward there, thanks for the tip

[Pradumna Saraf]

Thank you!

[zero]

Cool

[Pradumna Saraf]

Thank you, Zero

[joephill11]

this is very interesting and i never knew this had changed ive only been using docker a little over a year so this is good to know.

[wulu]

‌‌Thank you, this really helped me sort out my thoughts. I have two Raspberry Pis running different Linux distributions and Docker versions, which often confuses us. Now I'm much clearer.