How to convert docker compose to docker run
Each service in a compose file describes one container, and a docker run command describes the same container. To convert docker compose to docker run, the tool writes one command per service: the keys become options, so ports becomes -p, volumes becomes -v or --mount, environment becomes -e and restart becomes --restart. The image and the command go at the end.
services:
web:
image: nginx:1.27
ports:
- 8080:80
depends_on: [api]
api:
image: myorg/api:1.4
environment:
TAG: ${TAG:-prod}
# networks and volumes
docker network create app_default
# api
docker run -d \
--name api \
-e TAG=prod \
--network name=app_default,alias=api \
myorg/api:1.4
# web
docker run -d \
--name web \
-p 8080:80 \
--network name=app_default,alias=web \
nginx:1.27The file is read in your browser, as the Privacy Policy describes, which matters because compose files often hold passwords.
Start order and depends_on
Compose starts services in dependency order, and docker run does not, so the tool sorts the commands for you. A service comes after everything it lists in depends_on, in the list form and in the map form with conditions. links, volumes_from and network_mode: service:name count as dependencies too. Services that do not depend on each other keep the order of the file.
If the services depend on each other in a circle, no order exists. The tool stops and prints the circle, for example a → b → a, so you know which link to remove. A condition such as service_healthy cannot be reproduced by docker run, so the tool adds a note telling you to start that service first and wait for its health check.
Networks, volumes and the default network
Declared networks and volumes are created before the containers, with docker network create and docker volume create. The options of each are carried over: driver, internal, attachable, subnet and gateway for networks, driver and driver options for volumes. External ones are not created, and the notes say that they must already exist.
Compose gives every project a default network on which services find each other by name. A plain docker run does not. With Shared default network on and more than one service, the tool creates one network and attaches each container to it with its service name as an alias, so a connection string such as redis://cache:6379 keeps working. A service that lists its own networks is left on those.
Compose also puts the project name in front of the names it creates. The Project name option does the same, so a volume called data becomes app_data. Leave it empty to keep the plain names.
Anchors, variables and quoting
YAML anchors, aliases and merge keys are resolved before conversion, so a service that starts with <<: *common gets every key from the shared block. Keys that start with x- are extension fields and are ignored.
Values such as ${TAG:-prod}, ${TAG-prod}, ${TAG:+value}, ${TAG:?message} and $TAG are filled in the way Compose does it, including nested defaults. $$ becomes a literal dollar sign. A name you do not set stays as written inside single quotes, so the shell does not expand it, and it is listed so you can add it.
Quoting follows the shell you choose. Bash uses single quotes, PowerShell uses single quotes with doubled quotes inside, and the command prompt uses double quotes. A value with spaces, quotes or a dollar sign is quoted, and plain values are left alone.
x-c: &c
restart: always
services:
a:
<<: *c
image: x
# a
docker run -d \
--name a \
--restart always \
xWhich keys are converted
- Ports and storage: ports in short and long form, expose, volumes in short and long form, tmpfs, volumes_from, env_file and environment as a map or a list.
- Process and identity: image, container_name, command and entrypoint as a string or a list, user, working_dir, hostname, init, privileged, read_only, stdin_open and tty.
- Networking: networks with aliases and fixed addresses, network_mode, links, extra_hosts, dns, dns_search and dns_opt.
- Security and devices: cap_add, cap_drop, devices, device_cgroup_rules, security_opt, group_add, sysctls and ulimits.
- Health, logs and lifecycle: healthcheck, logging, restart, deploy.restart_policy, stop_signal, stop_grace_period and pull_policy.
- Resources: mem_limit, cpus, pids_limit, shm_size, the CPU and memory keys, deploy.resources limits and reservations, and GPU reservations as --gpus.
An entrypoint given as a list is split because docker run takes only the program after --entrypoint. The rest of the list is placed in front of the command, which is how Docker joins them.
What has no docker run equivalent
Some keys only exist in Compose or swarm: build, profiles, configs, secrets, extends, develop, scale, deploy.replicas, external_links and lifecycle hooks. The tool lists each one by service with the reason and does not guess. For a build key, run docker build first and use the image name the notes suggest.
Keys the tool does not know are listed as well. Relative paths such as ./nginx.conf are relative to the folder where you run the command, and several --network flags on one container need Docker 25 or newer. Both are noted when they apply. To go the other way, use Docker Run to Compose. To check or reshape the YAML first, YAML to JSON, JSON to YAML and Sort YAML Keys help.