Docker Compose ps Command: How to List Running Containers

Docker Compose is a powerful tool that simplifies managing multi-container Docker applications. One of the essential commands you’ll use in Docker is docker-compose ps. This command helps you monitor the status of services in your Docker Compose project.

In this guide, we’ll explore the docker compose ps command in detail, with practical examples that you can easily follow along.

Understanding the docker compose ps Command

The docker compose ps is your go-to tool for checking the status of your services. It displays information about the containers running in your Docker Compose project.

The basic syntax of docker compose ps is shown below:

 # docker-compose ps [OPTIONS]

Let’s break it down:

• docker-compose ps: This is the command itself.
• [OPTIONS]: These are optional flags to customize the output.

The docker-compose ps command will output a table with the following columns:

• Name: The name of the container.
• Command: The command the container is executing.
• State: The current status of the container (e.g., Up, Exit).
• Ports: Information about the container’s exposed ports.

Now, dive into some examples to see how the ps command works.

Example 1: Viewing the Status of All Services

When you want to check the status of all services in your project, simply use the docker-compose ps command without any options:

 # docker-compose ps

Output.

   Name                 Command               State               Ports
------------------------------------------------------------------------------
web_1         python app.py               Up                    0.0.0.0:5000->5000/tcp
db_1          docker-entrypoint.sh mysqld Up                    3306/tcp

This output shows the names of the services (web_1 and db_1), the commands they’re running, their current state (Up), and the ports they’re using.

Example 2: Filtering Services by State

Sometimes, you might want to see only the currently running services. You can do this with a simple filter:

 # docker-compose ps --filter "status=running"

Output.

   Name                 Command               State               Ports
------------------------------------------------------------------------------
web_1         python app.py               Up                    0.0.0.0:5000->5000/tcp

Now, only the running services will be shown in the output.

Example 3: Listing Containers with Extended Status Information

If you need more detailed information, like container IDs, you can use the -q option:

 # docker-compose ps -q

Output.

a1b2c3d4e5f6
g7h8i9j0k1l2

This output shows only the container IDs, which can be useful for scripting or further automation.

Example 4: Customizing the Output Format

You can also customize the output format. For example, to get the output in JSON format, use:

 # docker-compose ps --format json

Output.

[
    {
        "Name": "web_1",
        "Command": "python app.py",
        "State": "Up",
        "Ports": "0.0.0.0:5000->5000/tcp"
    },
    {
        "Name": "db_1",
        "Command": "docker-entrypoint.sh mysqld",
        "State": "Up",
        "Ports": "3306/tcp"
    }
]

JSON format can be handy when you need to process the output programmatically.

Example 5: Listing Containers Across Multiple Projects

If you are managing multiple Docker Compose projects, you can use the –project-name option to specify which project to list containers for:

 # docker-compose --project-name my_project ps

This is especially useful when running several projects on the same host, and you want to isolate the container information for a specific one.

Conclusion

The docker-compose ps command is an essential tool for managing Docker containers. It allows you to easily check the status of your containers, view important details, and troubleshoot issues. This guide provides practical examples for quickly listing running containers and monitoring their performance.

FAQs