docker-compose v1 to docker compose v2: what changed

Compose v1 was the Python docker-compose tool. Compose v2 is a rewrite in Go that ships as the docker compose plugin of the Docker CLI (Docker Desktop and the docker-compose-plugin package include it); later major versions continue the same line. Most files work unchanged, but a few behaviours differ.

The version key is obsolete

cat > docker-compose.yml <<'EOF'
version: "3.8"
name: demo
services:
  web:
    image: nginx:1.29
EOF
docker-compose config 2>&1 | sed 's/^time="[^"]*" //'

level=warning msg="/tmp/work/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion"
name: demo
services:
  web:
    image: nginx:1.29
    networks:
      default: null
networks:
  default:
    name: demo_default

Remove the line: Compose always uses the latest Compose Specification and no longer reads the version number.

Changes that affect scripts

Migration checklist

1. Replace docker-compose with docker compose in scripts and CI.
2. Delete the version: line.
3. Search for container names with underscores (_1) and switch to hyphens, or set container_name explicitly.
4. Optionally rename docker-compose.yml to compose.yaml.