Do You Still Need the version Field in Docker Compose? (2024 Update)

Docker Compose has evolved significantly over the years, and with the introduction of the new Compose Specification, many developers are wondering: Do I still need to specify the version: field in my docker-compose.yml?

The short answer: No, not anymore, if you’re using Docker Compose v1.27.0 or newer.

In this article, we’ll dive into:

• The purpose of the version: field in older Compose files
• Differences between Compose versions (2.x vs 3.x)
• What changed in the new Compose spec
• When (if ever) you still need to declare a version

🔍 What Was the Purpose of the version:  Field in Docker Compose?

In older versions of Docker Compose, the version: field was critical.
It determined how Docker would interpret your docker-compose.yml file and which features or syntax rules were available to you.

For example:

version: '3.8'
services:
  app:
    image: myapp:latest

Without this field, Docker wouldn’t know which Compose schema to use, especially when handling advanced features like networking, resource limits, or service dependencies.

⚖️ Key Differences Between Compose Versions: 2.x vs 3.x

Let’s take a look at how different versions affected features and behavior.

✅ Compose Version 2.x

• Targeted use: Local development environments
• Resource limits: Supported (mem_limit, cpu_shares, etc.)
• depends_on: Smart dependency resolution (wait for services to be ready)
• Flexible volume and network configurations

✅ Compose Version 3.x

• Targeted use: Docker Swarm deployments
• Resource limits: Only available via deploy.resources, and only in Swarm mode
• depends_on: Basic start-order only (no health checks or readiness)
• More rigid structure for orchestration compatibility

🔄 Why You Can Now Skip the version: Field

Starting from Docker Compose v1.27.0 (2020), the Docker team introduced the Compose Specification, a unified schema that makes the version: field optional.

Instead of relying on specific version numbers (‘2’, ‘3.4’, etc.), Compose CLI now auto-detects the correct behavior based on your configuration.

So you can go from this:

version: '3.9'
services:
  db:
    image: postgres

To this:

services:
  db:
    image: postgres

Much cleaner, right?

⚠️ Are There Any Situations Where You Still Need version:?

Technically no, as long as you’re using recent versions of Docker and Compose, and your team is aligned on a modern setup. However, if you’re working on legacy systems or CI/CD pipelines that run outdated Compose versions (prior to 1.27), you might still need the version: field.

Check your Compose version:

docker-compose version

Or if you’re using the newer CLI plugin:

docker compose version

🧠 Best Practices for Docker Compose in 2024

• ✅ Omit version: in new projects. Start directly with services:.
• ✅ Use the latest Docker Compose CLI for full spec support.
• 🚫 Avoid mixing Swarm features unless you’re explicitly deploying to a Swarm cluster.
• 📄 Document your Compose version in your README.md or project docs.

📌 Conclusion

If you’re still using version: in your Docker Compose files, it’s time to move forward. With the new Compose spec, you can write cleaner, more modern Compose files that are easier to maintain and forward-compatible with Docker’s evolving ecosystem.

If you’re not familiar with Docker Compose or unsure why it’s beneficial to use, check out our in-depth article titled What Is Docker Compose and Why Was It Created? Article Link: What Is Docker Compose and Why Was It Created?
In that article, we’ve thoroughly explained the core concept of Docker Compose and clearly outlined its key benefits to help you understand why it’s such a powerful and valuable tool for modern development workflows.

Want to learn more about Docker Compose best practices or YAML examples? Follow the blog or check out the official Compose spec!