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.

More docker tools

Docker Container Image Reference Parser Is that a registry or a Docker Hub user? Dockerfile Linter What this image will do to you later docker run to Kubernetes YAML And the flags that have no equivalent Docker Compose to Kubernetes And why depends_on has no equivalent Docker Logging Driver Generator json-file never rotates Dockerfile Non-Root USER Generator Numeric, or Kubernetes rejects it Docker OCI Image Labels Generator One of them actually does something Docker Hub Pull Rate Limit Calculator Counted per IP, not per person Docker Registry Storage Calculator Deleting a tag frees nothing Docker Build Context Analyzer All of it uploads before anything runs Docker Compose to docker run Converter Names stop resolving Docker Compose Network and Port Viewer Everything reaches everything Docker Command Explainer Which flags hand over the host Docker BuildKit Cache Mount Generator apt deletes the cache you just mounted Docker BuildKit Secret Mount Generator ARG is in docker history forever Docker .dockerignore Pattern Tester *.log does not match logs/app.log Docker Image Manifest Viewer unknown/unknown is not broken Docker Image Config Viewer Anyone who can pull can read your Env Docker Registry Token Decoder Check the scope before the credentials Docker HEALTHCHECK Generator Docker does nothing when it fails Docker Network Subnet Calculator 31 networks, then it stops Docker History Analyzer The rm did not save anything Docker Run to Compose Converter Some flags have no equivalent Docker CMD and ENTRYPOINT Tester Why docker stop takes ten seconds Docker Port Mapping Tester -p reaches past your firewall Docker -v to --mount Converter -v invents missing directories Docker Restart Policy Simulator The backoff resets after ten seconds Docker Exit Code Explainer 137 is two different problems Docker CPU Limit Converter --cpu-shares limits nothing Docker Memory Limit Calculator -m 512m allows a gigabyte Docker Compose Interpolation Tester An unset variable is an empty string Docker Environment Variable Precedence Tester Your shell does not reach the container Docker Compose Override Merge Previewer An override can add a port, never remove one Dockerfile Multi-Stage Build Analyzer Which stages reach the image Dockerignore Validator It is not .gitignore

Elsewhere on the site