Docker Compose — Version Field

1 minute read

If you’ve read older Docker Compose tutorials, you’ve seen a version: field at the top of compose files. This page explains what it was, why it’s gone, and what to do about it.

The Old Way

Compose V1 required a version: field to specify the compose file format:

# Old V1-era compose file
version: "3.8"
services:
  web:
    image: nginx

The version number determined which features were available:

Version Docker Engine Notable Features
2.0 1.10.0+ Networks, volumes
2.1 1.12.0+ Healthchecks
3.0 1.13.0+ Deploy key (Swarm)
3.8 19.03.0+ Last numbered version

The New Way

In Compose V2, the version: field is deprecated and completely ignored:

# Modern compose file — no version needed
services:
  web:
    image: nginx
    ports:
      - "80:80"

Compose V2 automatically supports all features. The version field is no longer needed because:

  1. All features are available — no gating by version number
  2. The Compose Specification replaced the numbered versions
  3. Backward compatibility — V2 reads any valid compose file

What Happens If You Include It?

# This still works — version is silently ignored
version: "3.8"
services:
  web:
    image: nginx

Compose V2 prints a warning:

WARN[0000] /path/to/compose.yml: the attribute `version` is obsolete,
it will be ignored, please remove it to avoid potential confusion

The file still works perfectly. The warning just nudges you to remove the line.

Migration Guide

Situation Action
New compose files Don’t include version:
Existing files with version: Remove it (or leave it — it’s ignored)
Shared files (V1 users on team) Leave version: for backward compatibility 
# Before (old style)
version: "3.8"
services:
  web:
    image: nginx

# After (modern style — just delete the version line)
services:
  web:
    image: nginx

Summary

Item Detail
version: field Deprecated, ignored by Compose V2
New files Don’t include it
Old files Remove it or leave it (harmless)
Warning Compose shows a warning if present
Replacement Compose Specification (all features always available)

Quick Reference

Item Detail
version field Deprecated — don’t include in new files
Compose V2 Ignores the version field completely
Warning Shows a warning if version is present
Migration Just delete the version: line
Compose Spec Replaces numbered versions
All features Always available in Compose V2

You may also enjoy