docker compose ps
| Description | List containers |
|---|---|
| Usage | docker compose ps [OPTIONS] [SERVICE...] |
Description
Lists containers for a Compose project, with current status and exposed ports.
$ docker compose ps
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
By default, only running containers are shown. --all flag can be used to include stopped containers.
$ docker compose ps --all
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
example-bar-1 alpine "/entrypoint.…" bar 4 seconds ago exited (0)
Options
| Option | Default | Description |
|---|---|---|
-a, --all | Show all stopped containers (including those created by the run command) | |
--filter | Filter services by a property (supported filters: status) | |
--format | table | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
--no-trunc | Don't truncate output | |
--orphans | true | Include orphaned services (not declared by project) |
-q, --quiet | Only display IDs | |
--services | Display services | |
--status | Filter services by status. Values: [paused | restarting | removing | running | dead | created | exited] |
Examples
Format the output (--format)
By default, the docker compose ps command uses a table ("pretty") format to
show the containers. The --format flag allows you to specify alternative
presentations for the output. Currently, supported options are pretty (default),
and json, which outputs information about the containers as JSON Lines
(one JSON object per line), aligned with the output of docker ps --format json:
$ docker compose ps --format json
{"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"}]}
The JSON output allows you to use the information in other tools for further
processing, for example, using the jq utility
to pretty-print each object:
$ docker compose ps --format json | jq .
{
"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"
}
]
}
Filter containers by status (--status)
Use the --status flag to filter the list of containers by status. For example,
to show only containers that are running or only containers that have exited:
$ docker compose ps --status=running
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
$ docker compose ps --status=exited
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
example-bar-1 alpine "/entrypoint.…" bar 4 seconds ago exited (0)
Filter containers by status (--filter)
The --status flag is a convenient shorthand for the --filter status=<status>
flag. The example below is the equivalent to the example from the previous section,
this time using the --filter flag:
$ docker compose ps --filter status=running
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp
The docker compose ps command currently only supports the --filter status=<status>
option, but additional filter options may be added in the future.