How to Use Docker Compose PS to List Containers

Use docker compose ps to list all containers managed by your Docker Compose setup, showing their current status and ports. This command helps you quickly see which containers are running, stopped, or exited in your project.

Syntax

The basic syntax of docker compose ps is simple and includes optional flags to customize output.

• docker compose ps: Lists containers in the current Compose project.
• -q: Shows only container IDs.
• --services: Lists only service names without container details.
• --filter: Filters containers by conditions like status.

bash

docker compose ps [OPTIONS]

Options:
  -q, --quiet       Only display container IDs
  --services        Display the service names
  --filter filter   Filter output based on conditions provided

Example

This example shows how to use docker compose ps to list containers and their status in a Compose project.

yaml and bash

version: '3.8'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
  db:
    image: postgres:alpine
    environment:
      POSTGRES_PASSWORD: example

# Run the following commands in terminal:
docker compose up -d

docker compose ps

Output

NAME                COMMAND                  SERVICE             STATUS              PORTS
myproject_web_1     "nginx -g 'daemon off;'"   web                 running             0.0.0.0:8080->80/tcp
myproject_db_1      "docker-entrypoint.s…"   db                  running             5432/tcp

Common Pitfalls

Common mistakes when using docker compose ps include:

• Running the command outside the directory with the docker-compose.yml file, resulting in no containers listed.
• Expecting docker compose ps to show all Docker containers, but it only shows those in the current Compose project.
• Not using -q when scripting, which can cause parsing issues if full details are expected.

bash

Wrong usage:

# Running outside project folder
cd ~
docker compose ps

# Output: No containers found

Right usage:

cd /path/to/project

docker compose ps

Output

NAME                COMMAND             SERVICE             STATUS              PORTS
myproject_web_1     "nginx -g 'daemon off;'"   web                 running             0.0.0.0:8080->80/tcp
myproject_db_1      "docker-entrypoint…"   db                  running             5432/tcp

Quick Reference

Option	Description
docker compose ps	List all containers in the current Compose project
docker compose ps -q	Show only container IDs
docker compose ps --services	Show only service names
docker compose ps --filter status=running	Show only running containers

Key Takeaways

Use docker compose ps to see containers managed by your Compose project and their status.

Run the command inside the directory with your docker-compose.yml file to get accurate results.

Use -q to get only container IDs for scripting or automation.

Remember docker compose ps shows only Compose-managed containers, not all Docker containers.