Debian Codegraph @

docs/reference/docker_compose_ps.yaml

raw
1 command: docker compose ps
2 short: List containers
3 long: |-
4 Lists containers for a Compose project, with current status and exposed ports.
5
6 ```console
7 $ docker compose ps
8 NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
9 example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
10 ```
11
12 By default, only running containers are shown. `--all` flag can be used to include stopped containers.
13
14 ```console
15 $ docker compose ps --all
16 NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
17 example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
18 example-bar-1 alpine "/entrypoint.…" bar 4 seconds ago exited (0)
19 ```
20 usage: docker compose ps [OPTIONS] [SERVICE...]
21 pname: docker compose
22 plink: docker_compose.yaml
23 options:
24 - option: all
25 shorthand: a
26 value_type: bool
27 default_value: "false"
28 description: |
29 Show all stopped containers (including those created by the run command)
30 deprecated: false
31 hidden: false
32 experimental: false
33 experimentalcli: false
34 kubernetes: false
35 swarm: false
36 - option: filter
37 value_type: string
38 description: 'Filter services by a property (supported filters: status)'
39 details_url: '#filter'
40 deprecated: false
41 hidden: false
42 experimental: false
43 experimentalcli: false
44 kubernetes: false
45 swarm: false
46 - option: format
47 value_type: string
48 default_value: table
49 description: |-
50 Format output using a custom template:
51 'table': Print output in table format with column headers (default)
52 'table TEMPLATE': Print output in table format using the given Go template
53 'json': Print in JSON format
54 'TEMPLATE': Print output using the given Go template.
55 Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates
56 details_url: '#format'
57 deprecated: false
58 hidden: false
59 experimental: false
60 experimentalcli: false
61 kubernetes: false
62 swarm: false
63 - option: no-trunc
64 value_type: bool
65 default_value: "false"
66 description: Don't truncate output
67 deprecated: false
68 hidden: false
69 experimental: false
70 experimentalcli: false
71 kubernetes: false
72 swarm: false
73 - option: orphans
74 value_type: bool
75 default_value: "true"
76 description: Include orphaned services (not declared by project)
77 deprecated: false
78 hidden: false
79 experimental: false
80 experimentalcli: false
81 kubernetes: false
82 swarm: false
83 - option: quiet
84 shorthand: q
85 value_type: bool
86 default_value: "false"
87 description: Only display IDs
88 deprecated: false
89 hidden: false
90 experimental: false
91 experimentalcli: false
92 kubernetes: false
93 swarm: false
94 - option: services
95 value_type: bool
96 default_value: "false"
97 description: Display services
98 deprecated: false
99 hidden: false
100 experimental: false
101 experimentalcli: false
102 kubernetes: false
103 swarm: false
104 - option: status
105 value_type: stringArray
106 default_value: '[]'
107 description: |
108 Filter services by status. Values: [paused | restarting | removing | running | dead | created | exited]
109 details_url: '#status'
110 deprecated: false
111 hidden: false
112 experimental: false
113 experimentalcli: false
114 kubernetes: false
115 swarm: false
116 inherited_options:
117 - option: dry-run
118 value_type: bool
119 default_value: "false"
120 description: Execute command in dry run mode
121 deprecated: false
122 hidden: false
123 experimental: false
124 experimentalcli: false
125 kubernetes: false
126 swarm: false
127 examples: |-
128 ### Format the output (--format) {#format}
129
130 By default, the `docker compose ps` command uses a table ("pretty") format to
131 show the containers. The `--format` flag allows you to specify alternative
132 presentations for the output. Currently, supported options are `pretty` (default),
133 and `json`, which outputs information about the containers as a JSON array:
134
135 ```console
136 $ docker compose ps --format json
137 [{"ID":"1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a","Name":"example-bar-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"bar","State":"exited","Health":"","ExitCode":0,"Publishers":null},{"ID":"f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0","Name":"example-foo-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"foo","State":"running","Health":"","ExitCode":0,"Publishers":[{"URL":"0.0.0.0","TargetPort":80,"PublishedPort":8080,"Protocol":"tcp"}]}]
138 ```
139
140 The JSON output allows you to use the information in other tools for further
141 processing, for example, using the [`jq` utility](https://stedolan.github.io/jq/)
142 to pretty-print the JSON:
143
144 ```console
145 $ docker compose ps --format json | jq .
146 [
147 {
148 "ID": "1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a",
149 "Name": "example-bar-1",
150 "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
151 "Project": "example",
152 "Service": "bar",
153 "State": "exited",
154 "Health": "",
155 "ExitCode": 0,
156 "Publishers": null
157 },
158 {
159 "ID": "f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0",
160 "Name": "example-foo-1",
161 "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
162 "Project": "example",
163 "Service": "foo",
164 "State": "running",
165 "Health": "",
166 "ExitCode": 0,
167 "Publishers": [
168 {
169 "URL": "0.0.0.0",
170 "TargetPort": 80,
171 "PublishedPort": 8080,
172 "Protocol": "tcp"
173 }
174 ]
175 }
176 ]
177 ```
178
179 ### Filter containers by status (--status) {#status}
180
181 Use the `--status` flag to filter the list of containers by status. For example,
182 to show only containers that are running or only containers that have exited:
183
184 ```console
185 $ docker compose ps --status=running
186 NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
187 example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
188
189 $ docker compose ps --status=exited
190 NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
191 example-bar-1 alpine "/entrypoint.…" bar 4 seconds ago exited (0)
192 ```
193
194 ### Filter containers by status (--filter) {#filter}
195
196 The [`--status` flag](#status) is a convenient shorthand for the `--filter status=<status>`
197 flag. The example below is the equivalent to the example from the previous section,
198 this time using the `--filter` flag:
199
200 ```console
201 $ docker compose ps --filter status=running
202 NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
203 example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
204 ```
205
206 The `docker compose ps` command currently only supports the `--filter status=<status>`
207 option, but additional filter options may be added in the future.
208 deprecated: false
209 hidden: false
210 experimental: false
211 experimentalcli: false
212 kubernetes: false
213 swarm: false
214