docker compose run
Description
Run a one-off command on a service.
Usage
$ docker compose run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l KEY=VALUE...] SERVICE [COMMAND] [ARGS...]
Extended description
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 app.py overrides it with
python app.py.
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 manage.py 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 127.0.0.1:2021:21 web python manage.py 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 manage.py 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 manage.py 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.
Options
| Name, shorthand | Default | Description |
--detach , -d |
Run container in background and print container ID | |
--entrypoint |
Override the entrypoint of the image | |
--env , -e |
Set environment variables | |
--labels , -l |
Add or override a label | |
--name |
Assign a name to the container | |
--no-TTY , -T |
Disable pseudo-noTty allocation. By default docker compose run allocates a TTY | |
--no-deps |
Don't start linked services. | |
--publish , -p |
Publish a container's port(s) to the host. | |
--rm |
Automatically remove the container when it exits | |
--service-ports |
Run command with the service's ports enabled and mapped to the host. | |
--use-aliases |
Use the service's network useAliases in the network(s) the container connects to. | |
--user , -u |
Run as specified username or uid | |
--volume , -v |
Bind mount a volume. | |
--workdir , -w |
Working directory inside the container |
Parent command
| Command | Description |
|---|---|
| docker compose | Docker Compose |
Related commands
| Command | Description |
| docker compose build | Build or rebuild services |
| docker compose convert | Converts the compose file to platform’s canonical format |
| docker compose cp | Copy files/folders between a service container and the local filesystem |
| docker compose create | Creates containers for a service. |
| docker compose down | Stop and remove containers, networks |
| docker compose events | Receive real time events from containers. |
| docker compose exec | Execute a command in a running container. |
| docker compose images | List images used by the created containers |
| docker compose kill | Force stop service containers. |
| docker compose logs | View output from containers |
| docker compose ls | List running compose projects |
| docker compose pause | pause services |
| docker compose port | Print the public port for a port binding. |
| docker compose ps | List containers |
| docker compose pull | Pull service images |
| docker compose push | Push service images |
| docker compose restart | Restart containers |
| docker compose rm | Removes stopped service containers |
| docker compose run | Run a one-off command on a service. |
| docker compose start | Start services |
| docker compose stop | Stop services |
| docker compose top | Display the running processes |
| docker compose unpause | unpause services |
| docker compose up | Create and start containers |