Docker Run to Compose

Common Use Cases

• Migration: Turn one-off docker run commands into reproducible compose configurations.
• Documentation: Convert run commands from README files or docs into compose format for your team.
• Multi-service setup: Generate individual service blocks and combine them into a single compose file.
• CI/CD: Replace fragile shell scripts of docker run commands with a declarative compose file.

Example: A PostgreSQL Container

Input:

docker run -d \
  --name postgres \
  -e POSTGRES_DB=myapp \
  -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  --restart unless-stopped \
  postgres:16-alpine

Output:

services:
  postgres:
    image: "postgres:16-alpine"
    ports:
      - "5432:5432"
    volumes:
      - "pgdata:/var/lib/postgresql/data"
    environment:
      - "POSTGRES_DB=myapp"
      - "POSTGRES_USER=admin"
      - "POSTGRES_PASSWORD=secret"
    restart: unless-stopped

volumes:
  pgdata:

pgdata is a named volume, so it is declared under the top-level volumes: key. Without that block Compose rejects the file: docker compose config reports service "postgres" refers to undefined volume pgdata. -d is dropped because you detach with docker compose up -d. --name becomes the service key; add container_name: yourself if scripts depend on the exact container name.

Example: Ports, Limits, and an Existing Network

docker run --rm -it --network app-net -p 127.0.0.1:8080:80/tcp \
  --restart on-failure:3 --memory 512m --cpus 1.5 --cap-add NET_ADMIN \
  ghcr.io/acme/web:1.2 npm start

services:
  acme_web:
    image: "ghcr.io/acme/web:1.2"
    ports:
      - "127.0.0.1:8080:80/tcp"
    networks:
      - app-net
    restart: "on-failure:3"
    cap_add:
      - NET_ADMIN
    stdin_open: true
    tty: true
    deploy:
      resources:
        limits:
          memory: 512m
          cpus: "1.5"
    command: ["npm", "start"]

networks:
  app-net:
    external: true

With no --name, the service key comes from the image (ghcr.io/acme/web:1.2 → acme_web). -it is the short options -i and -t together; they become stdin_open and tty. --rm is dropped. --network becomes an external network, so it must already exist (docker network create app-net). --network host, none, bridge, and container:NAME become network_mode: instead.

Example: Options Without a Compose Key

docker run -d --name web --env-file .env --entrypoint /bin/sh -u 1000:1000 -w /app --gpus all nginx:1.27 -c "nginx -g 'daemon off;'"

# Not converted: --gpus all
services:
  web:
    image: "nginx:1.27"
    entrypoint: ["/bin/sh"]
    env_file:
      - .env
    user: "1000:1000"
    working_dir: /app
    command: ["-c", "nginx -g 'daemon off;'"]

--entrypoint takes one executable in docker run, so it becomes a one-item list; the arguments after the image are the command. --gpus has no single Compose key (GPUs are reserved under deploy.resources.reservations.devices), so the converter reads its value, keeps the image name right, and lists it in the first-line comment and the status line.

Every output above passes docker compose config (Docker Compose 5.1); the tool’s test suite runs that check on each example.

Flag Mapping

Options can be written as --flag value, --flag=value, -p 80:80, -p80:80, or grouped (-dit, -dp 80:80), as the Docker CLI accepts.

Options to Add by Hand

These are read but not converted, because the Compose key has a different shape (services reference):

Limits

• One docker run command per conversion. For several containers, convert each one and put the service blocks under a single services: key.
• docker run and docker container run are recognised; podman run is not.
• Shell features such as $(...), $VAR, and && are kept as literal text. Expand variables before converting, or use Compose interpolation in the result.
• Relative bind paths such as ./data are relative to the compose file’s directory in Compose, and to the current directory in docker run.