Upgrades and deprecations
Docker Compose V1 to V2: Names, Commands and Files That Change
In short
Docker Compose v1 vs v2 now matters mostly for old servers and scripts. V1 stopped receiving updates in July 2023, and its last release, 1.29.2, dates from 10 May 2021. The switch is mostly a hyphen, but V2 names containers `project-service-1` instead of `project_service_1`, so its first `up` recreates containers that V1 started.
Is Compose V1 still maintained anywhere?
No. Docker's retired-features page lists Compose V1 as replaced by V2, no longer maintained, and says users should migrate. A Docker blog post from 31 January 2023 had already set the end: no V1 support after June 2023, and removal from all future Docker Desktop versions.
The Compose migration guide was itself retired from the docs; the old address now redirects to the retired-features page. Its last archived copy, from 1 January 2026, says V1 stopped receiving updates from July 2023 and that the final release, 1.29.2, came out on 10 May 2021 with no security updates since. PyPI shows the same version uploaded on that date.
Today the docs name two supported CLIs, Compose v2 and Compose v5, both driven by the Compose Specification. The history page calls v5 functionally identical to v2, released in 2025 with a Go SDK, and numbered 5 to avoid confusion with the old v2 and v3 file formats.
Checked against: source 1, source 2, source 3, source 4, source 5
Docker Compose v1 vs v2: what differs, row by row?
The table joins the archived migration guide, the history page and the Compose Specification. Rows cover only what those pages state.
| Area | Compose V1 | Compose V2 (and v5) |
|---|---|---|
| Program and command | Python, run as `docker-compose` | Go, a Docker CLI plugin run as `docker compose` |
| Container name for `-p myproject up --scale=1 svc` | `myproject_svc_1` | `myproject-svc-1` |
| Top-level `version:` | Picks a file format from 2.0 to 3.8 | Ignored; the spec calls it obsolete and prints a warning |
| File format 1 (no `services` key) | Runs | Does not run |
| Scaling | `docker-compose scale` (deprecated) | Not supported; use `docker compose up --scale` |
| `rm --all` | Deprecated | Not supported |
| `--compatibility` | Deprecated; migrates YAML fields by legacy schema version | Uses `_` in container names to match V1 |
| `ps --filter` | Undocumented filtering by any service property | Only set properties, for example `status=running` |
| Root `docker` flags | Separate program outside the Docker CLI | Shared, for example `--context`, `--tls` and `DOCKER_HOST` |
Why does the first V2 up recreate containers that are already running?
V2 builds container names from the project name, service name and replica number with hyphens, because underscores are not valid in DNS hostnames. When V2 runs up on a project that V1 started, the names do not match, so it recreates those containers under the new names.
The global --compatibility flag, or the COMPOSE_COMPATIBILITY variable, keeps underscores. The guide says it has to be given on every command and suggests it only as a temporary bridge. It also says the first V2 up still recreates V1 containers even with the flag, to migrate Compose's internal state. I would schedule that first up like a short deployment.
Names also depend on the project name. The docs rank -p first, then COMPOSE_PROJECT_NAME, then a top-level name:, then the directory name. Allowed characters are lowercase letters, digits, dashes and underscores, and the first must be a letter or digit. V1 rejects name: outright, covered in this fix page.
What happens to the version line in an old compose file?
Nothing breaks, but it stops meaning anything. The Compose Specification keeps version only for backward compatibility, calls it informative, and warns that it is obsolete. Compose always validates against the most recent schema, and it warns when it meets fields it does not know.
The history page explains why: file formats 2.x and 3.x were merged into one rolling specification, with backward compatibility for certain elements that changed between them. You can delete the line once nothing on the team runs V1. If V1 is the tool rejecting that line, see Compose refuses the version line.
Which environment variable cases need a second look?
The archived guide says V1's handling of variables was never formally documented and was inconsistent in edge cases, while V2 documents precedence and .env interpolation. It lists four things to check first.
- More than one level of overrides, such as a
.envfile plus--envflags. .envvalues with escape sequences or nested quotes.- Literal
$signs in values, which the guide says are common in PHP projects. See invalid interpolation format. - Advanced expansion such as
${VAR:?error}. - Run
docker compose configto see values after interpolation. The guide's rule for keeping V1 behaviour is to single-quote literal values and double-quote values that should be interpolated. If values never arrive, see env file values not applied.
Checked against: source 5
How do servers, CI images and scripts get V2?
Docker Desktop bundles V2 and, per the archived guide, keeps a docker-compose alias that forwards to docker compose. On a Linux server, the install page uses the docker-compose-plugin package from Docker's repository, with a manual download into a cli-plugins folder as the alternative. In CI, the guide says the official Docker image on Docker Hub includes V2, and docker/compose-bin packages it for multi-stage builds.
For scripts, the guide's advice is to replace the hyphen with a space. A server that still answers command not found for the hyphenated name is covered in this fix page.
sudo apt-get update
sudo apt-get install docker-compose-plugin
docker compose versionWhat else do people ask?
Can I still install Compose V1?
The archived guide says the packages can still be downloaded, but Docker gives no support and they have had no security updates since 1.29.2 in May 2021.
Is Compose v5 a different migration?
Not according to the history page. It describes v5 as functionally identical to v2 and governed by the same Compose Specification; the main addition is a Go SDK.
Sources
- Docker documentation, Retired and deprecated features (Docker Compose v1), fetched 2026-11-20
- Docker blog, Docker Compose, what's new, what's changing, what's next (31 January 2023), fetched 2026-11-20
- PyPI, docker-compose release metadata (1.29.2), fetched 2026-11-20
- Docker documentation, History and development of Docker Compose, fetched 2026-11-20
- Docker documentation, Migrate to Compose v2 (retired page, Internet Archive copy of 1 January 2026), fetched 2026-11-20
- Compose Specification, version and name top-level elements, fetched 2026-11-20
- Docker CLI reference, docker compose (global options), fetched 2026-11-20
- Docker documentation, Specify a project name, fetched 2026-11-20
- Docker documentation, Install the Docker Compose plugin on Linux, fetched 2026-11-20
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. This page compares Docker documents fetched on 20 Nov 2026, plus an archived copy of the retired Compose migration guide and the PyPI record. I did not migrate a Compose project for it. It does not cover Swarm, Podman, your own compose files or Docker Desktop settings. Found a mistake? Tell me.