How to use docker compose ps command to list containers

Introduction

In this lab, you will learn how to effectively use the docker compose ps command to list containers managed by Docker Compose. You will begin by installing Docker Compose and setting up a simple project with a docker-compose.yml file.

Following the setup, you will explore how to list only running containers, include stopped containers in the output, filter containers based on their status, and format the output as JSON for easier parsing and integration. This hands-on experience will equip you with the skills to monitor and manage your Docker Compose services efficiently.

Skills Graph

List running containers with docker compose ps

In this step, you will learn how to list running containers using docker compose ps. Before we can use docker compose, we need to install it.

First, let's install Docker Compose. We will download the latest stable release.

sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

This command downloads the Docker Compose binary for your system's architecture and saves it to /usr/local/bin/docker-compose.

Next, we need to apply executable permissions to the binary.

sudo chmod +x /usr/local/bin/docker-compose

Now, let's verify the installation by checking the version.

docker-compose --version

You should see the installed version of Docker Compose in the output.

To demonstrate docker compose ps, we need a docker-compose.yml file and some services to run. Let's create a simple docker-compose.yml file in your ~/project directory.

nano ~/project/docker-compose.yml

Add the following content to the file:

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  app:
    image: alpine:latest
    command: sleep infinity

This docker-compose.yml file defines two services: web using the nginx image and app using the alpine image. The web service maps port 80 on the host to port 80 in the container. The app service runs the sleep infinity command to keep the container running.

Save the file and exit the editor (Ctrl+X, Y, Enter).

Now, let's pull the necessary images.

docker pull nginx:latest
docker pull alpine:latest

These commands download the nginx:latest and alpine:latest images from Docker Hub.

Next, start the services defined in the docker-compose.yml file. Make sure you are in the ~/project directory.

cd ~/project
docker-compose up -d

The docker-compose up -d command builds, creates, starts, and attaches to containers for a service. The -d flag runs the containers in detached mode, meaning they run in the background.

Now that the containers are running, we can use docker compose ps to list them.

docker-compose ps

This command lists the running containers defined in your docker-compose.yml file. You should see output similar to this, showing the container names, commands, status, and ports.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-app-1       "sleep infinity"    app                 running
project-web-1       "/docker-entrypoint.sh nginx -g 'daemon off;'"   web                 running             0.0.0.0:80->80/tcp

The output shows the project-app-1 and project-web-1 containers are running. The NAME is typically the project name (the directory name) followed by the service name and a number.

List all containers including stopped ones

In the previous step, we used docker compose ps to list only the running containers. Sometimes, you might need to see all containers, including those that have stopped or exited.

To list all containers, including stopped ones, you can use the -a flag with the docker compose ps command.

First, let's stop one of the running containers to see the effect of the -a flag. We will stop the app service. Make sure you are in the ~/project directory.

cd ~/project
docker-compose stop app

This command stops the container for the app service. The container will no longer be running, but it will still exist.

Now, let's list the containers again using docker compose ps.

docker-compose ps

You should see that only the web container is listed as running. The app container is not shown because it is stopped.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-web-1       "/docker-entrypoint.sh nginx -g 'daemon off;'"   web                 running             0.0.0.0:80->80/tcp

Now, let's use the -a flag to list all containers, including the stopped one.

docker-compose ps -a

This command will show all containers defined in your docker-compose.yml file, regardless of their status.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-app-1       "sleep infinity"    app                 exited (0)
project-web-1       "/docker-entrypoint.sh nginx -g 'daemon off;'"   web                 running             0.0.0.0:80->80/tcp

You can see that both the project-app-1 and project-web-1 containers are listed. The STATUS column for project-app-1 shows exited, indicating that it is stopped.

Using docker compose ps -a is useful for seeing the state of all your services, even if they are not currently active.

Filter containers by status

In the previous steps, we learned how to list running containers and all containers. Sometimes, you might want to filter the list of containers based on their status.

The docker compose ps command allows you to filter the output using the --filter flag. You can filter by various criteria, including the container status.

The common container statuses are:

• created: The container has been created but not started.
• restarting: The container is in the process of restarting.
• running: The container is currently running.
• removing: The container is being removed.
• paused: The container is paused.
• exited: The container has stopped.
• dead: The container is dead.

Let's filter the containers to show only the running ones. We already know that docker compose ps by default shows running containers, but we can achieve the same using the filter. Make sure you are in the ~/project directory.

cd ~/project
docker-compose ps --filter status=running

This command will list only the containers with the status running. You should see only the web container listed.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-web-1       "/docker-entrypoint.sh nginx -g 'daemon off;'"   web                 running             0.0.0.0:80->80/tcp

Now, let's filter the containers to show only the exited ones. Remember that we stopped the app container in the previous step, so its status should be exited.

docker-compose ps --filter status=exited

This command will list only the containers with the status exited. You should see only the app container listed.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-app-1       "sleep infinity"    app                 exited (0)

You can also filter by multiple statuses by providing the --filter flag multiple times. For example, to list containers that are either running or exited:

docker-compose ps --filter status=running --filter status=exited

This command will list both the web and app containers.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-app-1       "sleep infinity"    app                 exited (0)
project-web-1       "/docker-entrypoint.sh nginx -g 'daemon off;'"   web                 running             0.0.0.0:80->80/tcp

Filtering by status is a powerful way to quickly find containers in a specific state, which is very useful for debugging and managing your services.

Format the output as JSON

In the previous steps, we listed and filtered containers using docker compose ps. By default, the output is formatted in a human-readable table. However, for scripting or integration with other tools, you might need the output in a structured format like JSON.

The docker compose ps command allows you to format the output using the --format flag. You can specify various formats, including json.

Let's list all containers (running and stopped) and format the output as JSON. Make sure you are in the ~/project directory.

cd ~/project
docker-compose ps -a --format json

This command will output the information about all containers in JSON format. The output will be a JSON array, where each element represents a container and its details.

[
  {
    "ID": "...",
    "Name": "project-app-1",
    "Image": "alpine:latest",
    "Command": "sleep infinity",
    "Project": "project",
    "Service": "app",
    "Created": "...",
    "State": "exited",
    "Status": "Exited (0) ...",
    "Health": "",
    "ExitCode": 0,
    "Publishers": []
  },
  {
    "ID": "...",
    "Name": "project-web-1",
    "Image": "nginx:latest",
    "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
    "Project": "project",
    "Service": "web",
    "Created": "...",
    "State": "running",
    "Status": "Up ...",
    "Health": "",
    "ExitCode": null,
    "Publishers": [
      {
        "URL": "0.0.0.0",
        "TargetPort": 80,
        "PublishedPort": 80,
        "Protocol": "tcp"
      }
    ]
  }
]

The JSON output provides a structured representation of the container information, making it easy to parse and process programmatically. Each container is represented as a JSON object with fields like ID, Name, Image, State, Status, etc.

Using the --format json flag is particularly useful when you need to extract specific information about your containers for automation or reporting purposes.

Finally, let's clean up the containers we created during this lab.

docker-compose down

This command stops and removes the containers, networks, and volumes created by docker-compose up.

Summary

In this lab, you learned how to use the docker compose ps command to list containers managed by Docker Compose. You started by installing Docker Compose and verifying its installation. Then, you created a simple docker-compose.yml file defining two services and pulled the necessary images. You used docker-compose up -d to start the services in detached mode.

You then explored the docker compose ps command to list running containers. You learned how to include stopped containers in the output using the -a flag, filter containers by status using the --filter status=<status> option, and format the output as JSON using the --format json option. Finally, you cleaned up the created resources by stopping and removing the services using docker-compose down.