Why convert docker run to Docker Compose?
A docker run command is convenient for starting a container, but a long command can be difficult to review or reproduce. A Compose file puts the same settings into named fields: the image, exposed ports, environment, mounts and restart policy can be read and edited together.
This Docker Run to Compose converter prepares a single-service compose.yaml file from your command. Use it as a starting point for documenting a container setup, moving a service to another server, or bringing a hand-written command into version control. It works locally in the browser and never connects to your Docker daemon.
How to convert a Docker command to Compose YAML
- Paste one
docker runordocker container runcommand. Commands split over lines should use backslash continuations. - Optionally enter a service name. Otherwise, the container name or image name is used.
- Read the conversion notes, particularly for external volumes, networks and launch-only options.
- Copy the output or download
compose.yaml. Place referenced files and bind-mounted directories in their intended locations. - Run
docker compose configlocally to check the Compose configuration before starting it.
For a long-running service, docker compose up -d starts it in the background. The converter does not run either command for you.
Docker run flags and their Compose equivalents
Short and long options are accepted, including forms such as -p8080:80, --name=web and -dit. Options must appear before the image; everything after the image is the container command.
| Docker run | Compose field | Conversion |
|---|---|---|
IMAGE | image | The image reference and tag are retained. |
--name | container_name | Also supplies the default service name. |
-p, --publish | ports | Host-to-container mappings stay quoted strings. |
-e, --env | environment | Supports NAME=value and host-provided NAME entries. |
--env-file | env_file | Uses raw format; requires Compose 2.30.0 or newer. |
-v, --volume | volumes | Supports bind mounts, named volumes and anonymous volumes. |
--mount | volumes | Supports bind and volume mounts with selected options. |
--network | networks / network_mode | Existing named networks are declared external. |
--restart | restart | Includes always, unless-stopped and on-failure. |
-u / -w | user / working_dir | Keeps the container user and working directory. |
--entrypoint | entrypoint | Preserves a single executable, without splitting spaces. |
Arguments after IMAGE | command | An argument list preserves quoting and empty arguments. |
-i / -t | stdin_open / tty | Interactive settings are included when requested. |
--memory / --cpus | mem_limit / cpus | Maps the container resource limits. |
--health-* | healthcheck | Maps the command, interval, timeout, start period and retries. |
--log-driver / --log-opt | logging | Retains the logging driver and options. |
Other supported settings include DNS, extra hosts, capabilities, devices, security options, labels, temporary filesystems, shared memory, process limits, read-only filesystems and privileged mode. An unsupported option stops conversion so it cannot disappear from the generated configuration unnoticed.
Example: a Docker run command becomes compose.yaml
This command starts an Nginx container named web, publishes host port 8080 and uses an automatic restart policy:
docker run -d --name web -p 8080:80 \
--restart unless-stopped nginx:alpineThe equivalent service configuration is:
services:
web:
image: "nginx:alpine"
container_name: "web"
ports:
- "8080:80"
restart: "unless-stopped"
network_mode: "bridge"Detached mode is a choice made when starting Compose, so -d becomes a launch instruction rather than a YAML field. The explicit bridge network preserves the default networking used by Docker run.
Keep the right data volumes and networks
A named Docker volume and a host directory are different kinds of mount. For -v data:/data, the converter declares data as an external volume with its exact name. This helps reuse an existing volume instead of accidentally starting with a new Compose project-prefixed volume. If this is a fresh setup, create the volume first or remove external: true.
For a bind mount such as -v ./html:/usr/share/nginx/html:ro, the relative path is interpreted beside the Compose file. Move the YAML file without its directory and the mount may point somewhere else. Absolute paths make the intended source explicit. A bind mount written with --mount keeps its stricter missing-source behavior through create_host_path: false.
Existing custom networks are also declared external. If your command does not specify a network, the output uses network_mode: bridge. Remove that field if you deliberately want Compose to create a project network and provide service-name discovery. Host networking cannot be combined with published ports in the generated configuration.
Supported input and conversion limits
The input is one POSIX-style shell command, optionally prefixed with sudo. Single and double quotes, escaped characters and backslash-newline continuations are supported. Windows PowerShell, CMD syntax, shell pipelines, redirections, multiple commands and Docker CLI global options are outside this converter’s scope.
The browser cannot read your shell environment or evaluate $(pwd). Replace shell variables and substitutions with resolved values before converting. Literal dollar signs inside single-quoted or escaped arguments are preserved with Compose’s $$ escaping. An environment entry without a value, such as -e API_TOKEN, is left for Compose to resolve on the deployment machine.
The converter preserves env-file contents using format: raw, which needs Docker Compose 2.30.0 or later. It does not open the referenced file, inspect an image, validate application credentials, check port availability or prove that a container will start. Use the generated file together with the conversion notes and a local configuration check.
Docker Run to Compose FAQ
Is this a free online converter?
Yes. You can paste a command, inspect the YAML, and copy or download it without creating an account. Conversion happens in your browser; the tool does not upload commands or execute them.
Why is there no version field?
The output uses the current Compose Specification with a top-level services mapping. It does not add the legacy version header. Use the modern docker compose command to validate and run the file.
What happens to --rm?
Automatic removal is a runtime choice, not a service field. For a one-off task, use docker compose run --rm --service-ports SERVICE, replacing SERVICE with your service name. The --service-ports option applies port mappings that Compose run otherwise does not publish by default.
Can I paste several docker run commands?
Convert one command at a time. To build a multi-service project, merge the generated service entries and reconcile shared volumes and networks manually. This tool does not infer dependencies between containers.
Why do I see an unsupported-option message?
Some Docker features need more context than a run command supplies. Flags such as --gpus, --link, extended network options and advanced mount settings currently require manual configuration. The tool withholds output instead of dropping those arguments.
Will the service name change my container name?
The optional service name changes the key under services. An explicit --name remains in container_name. If that name is already used by a running container, resolve the name conflict before starting Compose.
For details, consult the official Docker run reference, Compose service reference and Compose interpolation guide.
Related developer tools
- YAML to JSON converter — inspect configuration in JSON format.
- Online diff tool — compare configurations before and after a change.
- Cron expression generator — plan recurring server tasks.
- Docker VPS hosting — explore a server environment for container workloads.