How to use the command 'docker ps' (with examples)

The docker ps command is used to list Docker containers. It provides information about the running and stopped containers, including their status, names, and IDs. This command is essential for managing and monitoring containers in Docker.

Use case 1: List currently running docker containers

Code:

docker ps

Motivation: This use case is helpful when you want to quickly check all the currently running containers on your Docker host. It provides a concise overview of the containers that are actively running and can help you manage and troubleshoot your containers.

Explanation: The docker ps command without any additional arguments lists only the running containers. By default, it displays essential information such as container ID, image used, command, when it was created, and its status.

Example output:

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS               NAMES
eb90640e2fa8        nginx               "nginx -g 'daemon of…"   3 hours ago         Up 3 hours          80/tcp              nginx-container

Use case 2: List all docker containers (running and stopped)

Code:

docker ps --all

Motivation: This use case is useful when you want to see the complete list of containers, including both the running and stopped containers. It provides insight into the history of containers on your Docker host, allowing you to manage and remove them as needed.

Explanation: The --all or -a flag is used to list all containers, including those that are exited or stopped. By default, Docker only lists the running containers, but this flag extends it to show all containers.

Example output:

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS                         PORTS               NAMES
eb90640e2fa8        nginx               "nginx -g 'daemon of…"   3 hours ago         Up 3 hours                     80/tcp              nginx-container
f142fccb0f26        mysql               "docker-entrypoint.s…"   4 hours ago         Exited (0) 4 hours ago                             mysql-container

Use case 3: Show the latest created container (includes all states)

Code:

docker ps --latest

Motivation: Sometimes it’s necessary to identify the latest created container, regardless of its status (running, stopped, or exited). This use case is beneficial when you want to review the most recent container’s details and take appropriate action based on its status.

Explanation: The --latest flag lists the latest created container, including those in any state (running, exited, or stopped). It is helpful when you want to quickly identify the most recently created container.

Example output:

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS                         PORTS               NAMES
66b3cb82e013        redis               "docker-entrypoint.s…"   5 seconds ago       Up 5 seconds                   6379/tcp            redis-container

Use case 4: Filter containers that contain a substring in their name

Code:

docker ps --filter "name=name"

Motivation: When working with a large number of containers, it can be beneficial to filter them based on specific criteria. This use case allows you to filter containers that contain a specific substring in their name, making it easier to manage and identify relevant containers.

Explanation: The --filter flag is used to apply filters on the container list. By specifying name=<substring>, you can filter containers by a substring present in their name.

Example output:

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS                         PORTS               NAMES
eb90640e2fa8        nginx               "nginx -g 'daemon of…"   3 hours ago         Up 3 hours                     80/tcp              nginx-container

Use case 5: Filter containers that share a given image as an ancestor

Code:

docker ps --filter "ancestor=image:tag"

Motivation: When dealing with container orchestration or complex Docker setups, it can be beneficial to list containers that share a specific image as an ancestor. This use case helps identify containers connected to a common image for troubleshooting or management purposes.

Explanation: The --filter flag with the ancestor=<image:tag> filter allows you to filter containers that share the specified image and tag as their ancestor.

Example output:

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS                         PORTS               NAMES
eb90640e2fa8        nginx               "nginx -g 'daemon of…"   3 hours ago         Up 3 hours                     80/tcp              nginx-container

Use case 6: Filter containers by exit status code

Code:

docker ps --all --filter "exited=code"

Motivation: When investigating the behavior of containers, it can be helpful to filter them based on their exit status code. This use case allows you to focus on containers that have exited with a specific exit status code.

Explanation: The --all flag ensures that both running and exited containers are included in the list. The --filter flag with the exited=<code> filter restricts the list to containers that have exited with the specified exit status code.

Example output:

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS                         PORTS               NAMES
f142fccb0f26        mysql               "docker-entrypoint.s…"   4 hours ago         Exited (0) 4 hours ago                             mysql-container

Use case 7: Filter containers by status (created, running, removing, paused, exited, and dead)

Code:

docker ps --filter "status=status"

Motivation: When managing containers, it can be helpful to filter them based on their status. This use case allows you to list containers based on their status, such as created, running, paused, exited, or dead.

Explanation: The --filter flag with the status=<status> filter allows you to filter containers based on their status, as specified. The available status options include created, running, removing, paused, exited, and dead.

Example output:

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS                         PORTS               NAMES
eb90640e2fa8        nginx               "nginx -g 'daemon of…"   3 hours ago         Up 3 hours                     80/tcp              nginx-container

Use case 8: Filter containers that mount a specific volume or have a volume mounted in a specific path

Code:

docker ps --filter "volume=path/to/directory" --format "table .ID\t.Image\t.Names\t.Mounts"

Motivation: When working with containers that have volumes, it can be helpful to filter them based on specific volume-related criteria. This use case allows you to list containers that either mount a specific volume or have a volume mounted in a specific path.

Explanation: The --filter flag with the volume=<path> filter allows you to filter containers that mount the specified volume. Additionally, the --format flag is used to customize the output table, displaying only the container ID, image, names, and mounts.

Example output:

CONTAINER ID        IMAGE               NAMES                        MOUNTS
eb90640e2fa8        nginx               nginx-container              /path/to/directory:/mnt/volume

Conclusion:

The docker ps command is a versatile tool for managing Docker containers. It allows you to list and filter containers based on various criteria such as their state, image, name, and volume-related properties. Understanding the different options provided by this command enables effective management and monitoring of Docker containers.