The official documentation has preferred the name compose.yaml for quite a while, but many tutorials and existing projects still use docker-compose.yml. Is there a practical difference between the two, and is there any downside to continuing with compose.yaml? Also, are compose.yml and the older version field still supported?
4 Answers
The version field at the top is generally no longer needed with the current Compose specification. Older examples often include it, but Compose now uses the specification directly and usually treats that field as obsolete.
The difference is mostly convention. compose.yaml is shorter and provider-neutral, so it’s a sensible choice for new projects. Existing docker-compose.yml files aren’t likely to stop working soon, and renaming them later is easy if support ever changes.
compose.yml is accepted too, but the documentation specifically recommends compose.yaml. The .yaml extension is just the longer, standard spelling; the important part is that the file contains valid Compose YAML and is named in a way the tool discovers automatically.
You’re not doing anything wrong. compose.yaml is the current preferred name in the Compose specification, while docker-compose.yml mostly persists because of older tutorials and muscle memory from the original Python-based tool. Modern Docker Compose accepts both names.
A lot of guides simply copy older configuration files without updating the naming or removing the now-obsolete version field.