DOCKER-COMPOSE-PS(1)

okay so bestie, buckle up 💖 you just opened the docker-compose-ps(1) manual page, and honestly? it's a good one. it's the "who's even alive in my project rn" command. no cap.

---

🎀 NAME 🎀

docker-compose-ps — list containers 💅

---

✨ SYNOPSIS ✨

docker compose ps [OPTIONS] [SERVICE...]

---

💖 DESCRIPTION 💖

It lists the containers in a Compose project, showing you their current status and the exposed ports. basically a little roll call for your lil guys.

$ 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. if you wanna see the ones that have, like, departed, hit the --all flag to include stopped containers too. 🫶

$ 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 🔥

• -a, --all[=false] — show all stopped containers (including those created by the run command). the "come back, i miss you" flag fr fr.
• --filter="" — filter services by a property (supported filters: status)
• --format="table" — format output using a custom template. the tea is:
  • 'table': print output in table format with column headers (this is the 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.

• -h, --help[=false] — help for ps 🥺
• --no-trunc[=false] — don't truncate output. give me the FULL thing, i wanna see every character, periodt.
• --orphans[=true] — include orphaned services (not declared by project). the ones nobody claims. we still love them. 🙈
• -q, --quiet[=false] — only display IDs
• --services[=false] — display services
• --status=[] — filter services by status. values: [paused | restarting | removing | running | dead | created | exited]

---

🌈 OPTIONS INHERITED FROM PARENT COMMANDS 🌈

• --dry-run[=false] — execute command in dry run mode. a little rehearsal, a little dress rehearsal, no actual consequences. iconic.

---

🦋 EXAMPLE 🦋

Format the output (--format) {#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 https://stedolan.github.io/jq/ 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) {#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) {#filter}

The status 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.

ok and yes, bestie, there is literally a stray ``` sitting at the very end of that section in the original page. not mine. i just report what i see 💀

---

👑 SEE ALSO 👑

docker-compose(1)

---

and that's the whole page, gorgeous. this one's dated Mar 2025, so go forth and docker compose ps your little heart out. slay, ate, no crumbs left 💅✨🎀🦋🌸💖🫶