docker compose run

DescriptionRun a one-off command on a service
Usagedocker compose run [OPTIONS] SERVICE [COMMAND] [ARGS...]


Runs a one-time command against a service.

The following command starts the web service and runs bash as its command:

$ docker compose run web bash

Commands you use with run start in new containers with configuration defined by that of the service, including volumes, links, and other details. However, there are two important differences:

First, the command passed by run overrides the command defined in the service configuration. For example, if the web service configuration is started with bash, then docker compose run web python overrides it with python

The second difference is that the docker compose run command does not create any of the ports specified in the service configuration. This prevents port collisions with already-open ports. If you do want the service’s ports to be created and mapped to the host, specify the --service-ports

$ docker compose run --service-ports web python shell

Alternatively, manual port mapping can be specified with the --publish or -p options, just as when using docker run:

$ docker compose run --publish 8080:80 -p 2022:22 -p web python shell

If you start a service configured with links, the run command first checks to see if the linked service is running and starts the service if it is stopped. Once all the linked services are running, the run executes the command you passed it. For example, you could run:

$ docker compose run db psql -h db -U docker

This opens an interactive PostgreSQL shell for the linked db container.

If you do not want the run command to start linked containers, use the --no-deps flag:

$ docker compose run --no-deps web python shell

If you want to remove the container after running while overriding the container’s restart policy, use the --rm flag:

$ docker compose run --rm web python db upgrade

This runs a database upgrade script, and removes the container when finished running, even if a restart policy is specified in the service configuration.


--buildBuild image before starting container
--cap-addAdd Linux capabilities
--cap-dropDrop Linux capabilities
-d, --detachRun container in background and print container ID
--entrypointOverride the entrypoint of the image
-e, --envSet environment variables
-i, --interactivetrueKeep STDIN open even if not attached
-l, --labelAdd or override a label
--nameAssign a name to the container
-T, --no-TTYtrueDisable pseudo-TTY allocation (default: auto-detected)
--no-depsDon't start linked services
-p, --publishPublish a container's port(s) to the host
--quiet-pullPull without printing progress information
--remove-orphansRemove containers for services not defined in the Compose file
--rmAutomatically remove the container when it exits
-P, --service-portsRun command with all service's ports enabled and mapped to the host
--use-aliasesUse the service's network useAliases in the network(s) the container connects to
-u, --userRun as specified username or uid
-v, --volumeBind mount a volume
-w, --workdirWorking directory inside the container