Docker Compose Version Migrator

Bring a Compose file up to the Compose Specification. For most files the whole migration is deleting one line, and the rest is things that were always questionable.

Paste below, or drop a file anywhere on this panel

Or drop a file anywhere on this panel. Nothing is uploaded: the analysis runs in this tab.

The answer appears here

Paste on the left and press Migrate. Nothing leaves this tab.

Examples

Real input you can load into the tool above. Each one shows a different thing going wrong, because that is what the tool is for.

A 3.8 file with the usual legacy

The version key, a fixed container name, and a depends_on that does not wait for readiness

version: "3.8"
services:
  web:
    image: nginx
    container_name: my-web
    depends_on:
      - db
  db:
    image: postgres:16

Swarm keys outside Swarm

replicas is silently ignored, and deploy.resources is not

services:
  web:
    image: nginx
    deploy:
      replicas: 3

Common mistakes

These are the ones that fail silently. The config is accepted, nothing raises an error, and the consequence arrives later.

  1. Keeping the version key to be safe

    It selects nothing and produces a warning on every command, which is how teams learn to ignore Compose's warnings.

    Instead:Delete it. Nothing else changes.

  2. Using the short depends_on and expecting readiness

    It waits for the container to start, not for the service to accept connections, so the dependent starts too early and exits.

    Instead:Use the long form with condition: service_healthy, and give the dependency a healthcheck.

  3. Setting replicas under deploy without Swarm

    docker compose up ignores it silently, so the file says three and one runs.

    Instead:Use --scale on the command line, or accept one. deploy.resources is the only subkey Compose honours.

There is one specification now, and the version key means nothing

The 2.x and 3.x split existed because 3.x was written for Swarm and dropped keys 2.x had. The Compose Specification merged them, and the key that used to select between them is obsolete.

Compose v2 warns about it on every command

Which is noise on every up, down and config, and noise trains people to stop reading warnings. Deleting the line changes nothing else: v2 reads every file the same way regardless of what the key said.

mem_limit and cpus work again

They were the casualties of the 3.x split and are back at the service level in the specification. So you do not need a deploy block to set a memory limit outside Swarm.

Most of deploy is still Swarm-only

replicas, placement, update_config and restart_policy under deploy are silently ignored by docker compose up. deploy.resources IS honoured, which is the confusing part: one subkey works and the rest are decoration.

The short depends_on waits for start, not readiness

A database container starts in a second and accepts connections some time later. The short form is satisfied by the first, so the application starts, fails to connect and exits. Everybody meets this once and concludes depends_on is broken; it is doing exactly what it says.

container_name prevents scaling and collides across projects

Docker container names are unique per host, so a fixed one means exactly one replica and refuses to coexist with another project using the same name.