docker compose ps

Description

List containers

Usage

$ docker compose ps [SERVICE...]

Extended description

Lists containers for a Compose project, with current status and exposed ports. By default, both running and stopped containers are shown:

$ docker compose ps
NAME           COMMAND                  SERVICE   STATUS       PORTS
example-bar-1  "/docker-entrypoint.…"   bar       exited (0)
example-foo-1  "/docker-entrypoint.…"   foo       running      0.0.0.0:8080->80/tcp

For example uses of this command, refer to the examples section below.

Options

Name, shorthand Default Description
--all , -a Show all stopped containers (including those created by the run command)
--filter Filter services by a property (supported filters: status).
--format pretty Format the output. Values: [pretty | json]
--quiet , -q 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 a JSON array:

$ 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 the JSON:

$ 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           COMMAND                  SERVICE   STATUS       PORTS
example-foo-1  "/docker-entrypoint.…"   foo       running      0.0.0.0:8080->80/tcp

$ docker compose ps --status=exited
NAME           COMMAND                  SERVICE   STATUS       PORTS
example-bar-1  "/docker-entrypoint.…"   bar       exited (0)

Filter containers by status (--filter)

The --status flag is a convenience 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           COMMAND                  SERVICE   STATUS       PORTS
example-foo-1  "/docker-entrypoint.…"   foo       running      0.0.0.0:8080->80/tcp

$ docker compose ps --filter status=running
NAME           COMMAND                  SERVICE   STATUS       PORTS
example-bar-1  "/docker-entrypoint.…"   bar       exited (0)

The docker compose ps command currently only supports the --filter status=<status> option, but additional filter options may be added in future.

Parent command

Command Description
docker compose Docker Compose
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
docker compose version Show the Docker Compose version information