Debian Codegraph @

docs/reference/compose_ps.md

raw
1 # docker compose ps
2
3 <!---MARKER_GEN_START-->
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
21 ### Options
22
23 | Name | Type | Default | Description |
24 |:----------------------|:--------------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
25 | `-a`, `--all` | `bool` | | Show all stopped containers (including those created by the run command) |
26 | `--dry-run` | `bool` | | Execute command in dry run mode |
27 | [`--filter`](#filter) | `string` | | Filter services by a property (supported filters: status) |
28 | [`--format`](#format) | `string` | `table` | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
29 | `--no-trunc` | `bool` | | Don't truncate output |
30 | `--orphans` | `bool` | `true` | Include orphaned services (not declared by project) |
31 | `-q`, `--quiet` | `bool` | | Only display IDs |
32 | `--services` | `bool` | | Display services |
33 | [`--status`](#status) | `stringArray` | | Filter services by status. Values: [paused \| restarting \| removing \| running \| dead \| created \| exited] |
34
35
36 <!---MARKER_GEN_END-->
37
38 ## Description
39
40 Lists containers for a Compose project, with current status and exposed ports.
41
42 ```console
43 $ docker compose ps
44 NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
45 example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
46 ```
47
48 By default, only running containers are shown. `--all` flag can be used to include stopped containers.
49
50 ```console
51 $ docker compose ps --all
52 NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
53 example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
54 example-bar-1 alpine "/entrypoint.…" bar 4 seconds ago exited (0)
55 ```
56
57 ## Examples
58
59 ### <a name="format"></a> Format the output (--format)
60
61 By default, the `docker compose ps` command uses a table ("pretty") format to
62 show the containers. The `--format` flag allows you to specify alternative
63 presentations for the output. Currently, supported options are `pretty` (default),
64 and `json`, which outputs information about the containers as a JSON array:
65
66 ```console
67 $ docker compose ps --format json
68 [{"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"}]}]
69 ```
70
71 The JSON output allows you to use the information in other tools for further
72 processing, for example, using the [`jq` utility](https://stedolan.github.io/jq/)
73 to pretty-print the JSON:
74
75 ```console
76 $ docker compose ps --format json | jq .
77 [
78 {
79 "ID": "1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a",
80 "Name": "example-bar-1",
81 "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
82 "Project": "example",
83 "Service": "bar",
84 "State": "exited",
85 "Health": "",
86 "ExitCode": 0,
87 "Publishers": null
88 },
89 {
90 "ID": "f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0",
91 "Name": "example-foo-1",
92 "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
93 "Project": "example",
94 "Service": "foo",
95 "State": "running",
96 "Health": "",
97 "ExitCode": 0,
98 "Publishers": [
99 {
100 "URL": "0.0.0.0",
101 "TargetPort": 80,
102 "PublishedPort": 8080,
103 "Protocol": "tcp"
104 }
105 ]
106 }
107 ]
108 ```
109
110 ### <a name="status"></a> Filter containers by status (--status)
111
112 Use the `--status` flag to filter the list of containers by status. For example,
113 to show only containers that are running or only containers that have exited:
114
115 ```console
116 $ docker compose ps --status=running
117 NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
118 example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
119
120 $ docker compose ps --status=exited
121 NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
122 example-bar-1 alpine "/entrypoint.…" bar 4 seconds ago exited (0)
123 ```
124
125 ### <a name="filter"></a> Filter containers by status (--filter)
126
127 The [`--status` flag](#status) is a convenient shorthand for the `--filter status=<status>`
128 flag. The example below is the equivalent to the example from the previous section,
129 this time using the `--filter` flag:
130
131 ```console
132 $ docker compose ps --filter status=running
133 NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
134 example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
135 ```
136
137 The `docker compose ps` command currently only supports the `--filter status=<status>`
138 option, but additional filter options may be added in the future.