Docker Compose — Compose V1 vs V2

3 minute read

Docker Compose has gone through a major evolution. Compose V1 was a standalone Python tool. Compose V2 is a Go-based plugin built directly into the Docker CLI. Understanding this history helps you avoid confusion when reading older tutorials.

The History of Docker Compose

Timeline:
─────────────────────────────────────────────────────────
2014        2016        2020         2023        Now
  │           │           │            │          │
  ▼           ▼           ▼            ▼          ▼
Fig        Compose     Compose V2   V1 EOL    V2 only
created    V1 stable   released     announced  standard
(Python)   (Python)    (Go plugin)  (June)
─────────────────────────────────────────────────────────
  • 2014 — Docker acquires Fig, a tool by Orchard Labs for defining multi-container apps
  • 2014 — Fig is renamed to Docker Compose (V1), written in Python
  • 2020 — Docker releases Compose V2 as a Go-based Docker CLI plugin
  • 2023 — Compose V1 reaches end of life — no more updates
  • Now — Compose V2 is the only supported version

Key Differences

Feature Compose V1 Compose V2
Command docker-compose (hyphen) docker compose (space)
Language Python Go
Installation Separate binary Docker CLI plugin (bundled)
Performance Slower startup 2-3x faster
Container naming project_service_1 (underscore) project-service-1 (hyphen)
Profiles ❌ Not supported ✅ Supported
Watch mode ❌ Not supported ✅ Supported
include: ❌ Not supported ✅ Supported
GPU support Limited Full support
Status ⚠️ End of life ✅ Active development

The Command Change

The most visible difference: the hyphen became a space.

# V1 — standalone binary (DEPRECATED)
docker-compose up -d
docker-compose down
docker-compose ps

# V2 — Docker CLI plugin (USE THIS)
docker compose up -d
docker compose down
docker compose ps

If you see docker-compose (with a hyphen) in a tutorial, blog post, or Stack Overflow answer, it’s using the old V1 syntax. Replace the hyphen with a space and the command works the same way in V2.

Container Naming Change

V1 and V2 name containers differently:

# V1 naming (underscores, trailing number)
myapp_web_1
myapp_db_1

# V2 naming (hyphens, trailing number)
myapp-web-1
myapp-db-1

This matters if you have scripts that reference container names. Update them when migrating from V1 to V2.

Checking Your Version

docker compose version

Expected output:

Docker Compose version v2.24.0

If you get command not found, you need to install Docker Desktop or the Compose plugin. See Chapter 2 — Installation.

If you still have V1 installed:

docker-compose --version

docker-compose version 1.29.2, build 5becea4c

Migrating from V1 to V2

Migration is usually seamless. Here’s what to check:

  1. Command syntax — Replace docker-compose with docker compose
  2. Container names — Underscores become hyphens
  3. Scripts — Update any scripts referencing old container names
  4. CI/CD — Update pipeline commands
  5. version: field — No longer needed in V2 (but doesn’t cause errors)
# Test V2 compatibility with your existing compose file
docker compose config

If docker compose config outputs your resolved YAML without errors, you’re good to go.

The version Field

In V1, compose files started with a version: field:

# V1 era — version field was required
version: "3.8"
services:
  web:
    image: nginx

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

# V2 era — no version field needed
services:
  web:
    image: nginx

If your existing files have version:, leave it or remove it — V2 ignores it either way. For new files, don’t include it.

Summary

Item Detail
V1 command docker-compose (hyphen) — deprecated
V2 command docker compose (space) — use this
V1 naming project_service_1 (underscores)
V2 naming project-service-1 (hyphens)
V1 status End of life (June 2023)
V2 status Active development, bundled with Docker
Migration Usually seamless — update commands and names

Quick Reference

Item Detail
docker compose (space) V2 command — use this
docker-compose (hyphen) V1 command — deprecated
version field No longer needed in V2
Container naming V2 uses hyphens: project-service-1
docker compose config Validate your compose file
Performance V2 is 2-3x faster than V1

← What is Docker Compose When to Use Compose →

You may also enjoy