Debian Codegraph @

docs/reference/compose_run.md

raw
1 # docker compose run
2
3 <!---MARKER_GEN_START-->
4 Runs a one-time command against a service.
5
6 The following command starts the `web` service and runs `bash` as its command:
7
8 ```console
9 $ docker compose run web bash
10 ```
11
12 Commands you use with run start in new containers with configuration defined by that of the service,
13 including volumes, links, and other details. However, there are two important differences:
14
15 First, the command passed by `run` overrides the command defined in the service configuration. For example, if the
16 `web` service configuration is started with `bash`, then `docker compose run web python app.py` overrides it with
17 `python app.py`.
18
19 The second difference is that the `docker compose run` command does not create any of the ports specified in the
20 service configuration. This prevents port collisions with already-open ports. If you do want the service’s ports
21 to be created and mapped to the host, specify the `--service-ports`
22
23 ```console
24 $ docker compose run --service-ports web python manage.py shell
25 ```
26
27 Alternatively, manual port mapping can be specified with the `--publish` or `-p` options, just as when using docker run:
28
29 ```console
30 $ docker compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell
31 ```
32
33 If you start a service configured with links, the run command first checks to see if the linked service is running
34 and starts the service if it is stopped. Once all the linked services are running, the run executes the command you
35 passed it. For example, you could run:
36
37 ```console
38 $ docker compose run db psql -h db -U docker
39 ```
40
41 This opens an interactive PostgreSQL shell for the linked `db` container.
42
43 If you do not want the run command to start linked containers, use the `--no-deps` flag:
44
45 ```console
46 $ docker compose run --no-deps web python manage.py shell
47 ```
48
49 If you want to remove the container after running while overriding the container’s restart policy, use the `--rm` flag:
50
51 ```console
52 $ docker compose run --rm web python manage.py db upgrade
53 ```
54
55 This runs a database upgrade script, and removes the container when finished running, even if a restart policy is
56 specified in the service configuration.
57
58 ### Options
59
60 | Name | Type | Default | Description |
61 |:------------------------|:--------------|:---------|:---------------------------------------------------------------------------------|
62 | `--build` | `bool` | | Build image before starting container |
63 | `--cap-add` | `list` | | Add Linux capabilities |
64 | `--cap-drop` | `list` | | Drop Linux capabilities |
65 | `-d`, `--detach` | `bool` | | Run container in background and print container ID |
66 | `--dry-run` | `bool` | | Execute command in dry run mode |
67 | `--entrypoint` | `string` | | Override the entrypoint of the image |
68 | `-e`, `--env` | `stringArray` | | Set environment variables |
69 | `--env-from-file` | `stringArray` | | Set environment variables from file |
70 | `-i`, `--interactive` | `bool` | `true` | Keep STDIN open even if not attached |
71 | `-l`, `--label` | `stringArray` | | Add or override a label |
72 | `--name` | `string` | | Assign a name to the container |
73 | `-T`, `--no-TTY` | `bool` | `true` | Disable pseudo-TTY allocation (default: auto-detected) |
74 | `--no-deps` | `bool` | | Don't start linked services |
75 | `-p`, `--publish` | `stringArray` | | Publish a container's port(s) to the host |
76 | `--pull` | `string` | `policy` | Pull image before running ("always"\|"missing"\|"never") |
77 | `-q`, `--quiet` | `bool` | | Don't print anything to STDOUT |
78 | `--quiet-build` | `bool` | | Suppress progress output from the build process |
79 | `--quiet-pull` | `bool` | | Pull without printing progress information |
80 | `--remove-orphans` | `bool` | | Remove containers for services not defined in the Compose file |
81 | `--rm` | `bool` | | Automatically remove the container when it exits |
82 | `-P`, `--service-ports` | `bool` | | Run command with all service's ports enabled and mapped to the host |
83 | `--use-aliases` | `bool` | | Use the service's network useAliases in the network(s) the container connects to |
84 | `-u`, `--user` | `string` | | Run as specified username or uid |
85 | `-v`, `--volume` | `stringArray` | | Bind mount a volume |
86 | `-w`, `--workdir` | `string` | | Working directory inside the container |
87
88
89 <!---MARKER_GEN_END-->
90
91 ## Description
92
93 Runs a one-time command against a service.
94
95 The following command starts the `web` service and runs `bash` as its command:
96
97 ```console
98 $ docker compose run web bash
99 ```
100
101 Commands you use with run start in new containers with configuration defined by that of the service,
102 including volumes, links, and other details. However, there are two important differences:
103
104 First, the command passed by `run` overrides the command defined in the service configuration. For example, if the
105 `web` service configuration is started with `bash`, then `docker compose run web python app.py` overrides it with
106 `python app.py`.
107
108 The second difference is that the `docker compose run` command does not create any of the ports specified in the
109 service configuration. This prevents port collisions with already-open ports. If you do want the service’s ports
110 to be created and mapped to the host, specify the `--service-ports`
111
112 ```console
113 $ docker compose run --service-ports web python manage.py shell
114 ```
115
116 Alternatively, manual port mapping can be specified with the `--publish` or `-p` options, just as when using docker run:
117
118 ```console
119 $ docker compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell
120 ```
121
122 If you start a service configured with links, the run command first checks to see if the linked service is running
123 and starts the service if it is stopped. Once all the linked services are running, the run executes the command you
124 passed it. For example, you could run:
125
126 ```console
127 $ docker compose run db psql -h db -U docker
128 ```
129
130 This opens an interactive PostgreSQL shell for the linked `db` container.
131
132 If you do not want the run command to start linked containers, use the `--no-deps` flag:
133
134 ```console
135 $ docker compose run --no-deps web python manage.py shell
136 ```
137
138 If you want to remove the container after running while overriding the container’s restart policy, use the `--rm` flag:
139
140 ```console
141 $ docker compose run --rm web python manage.py db upgrade
142 ```
143
144 This runs a database upgrade script, and removes the container when finished running, even if a restart policy is
145 specified in the service configuration.