How to Use the Command 'podman ps' (with Examples)

Podman is a tool for managing OCI containers and pods, which allows for seamless container deployment, management, and orchestration on Linux systems. One of the fundamental commands within Podman is podman ps, an essential utility for viewing information about containers. This command is used to display a list of running or available containers, providing various options to filter and format the output comprehensively. In this article, we explore various use cases of the podman ps command with detailed examples demonstrating its capabilities.

Use Case 1: List Currently Running Podman Containers

Code:

podman ps

Motivation: For system administrators and developers, monitoring active containers is crucial for managing applications and services in a containerized environment. Using podman ps, you can quickly identify which containers are operational, ensuring that essential services are running smoothly.

Explanation:

• podman ps: This command alone lists all currently active or running containers. It does not include containers that are stopped, paused, or in any other state, focusing only on those currently executing processes.

Example Output:

CONTAINER ID  IMAGE                  COMMAND      CREATED         STATUS             PORTS     NAMES
ea3519c89a9f  ubuntu:latest          bash         2 hours ago     Up 2 hours                   joyful_cray
cdfebe2c9d7a  nginx:alpine           nginx        3 hours ago     Up About an hour   80/tcp    fervent_goldwasser

Use Case 2: List All Podman Containers (Running and Stopped)

Code:

podman ps --all

Motivation: In container lifecycle management, it is often necessary to see more than just the currently running containers. Viewing all containers, including stopped, exited, and paused ones, provides a complete overview of container resources and helps in tracking which containers may require troubleshooting or which need to be restarted.

Explanation:

• --all: This flag extends the functionality of podman ps by listing every container irrespective of their current state. This comprehensive list includes containers that are active, exited, created but never started, and so forth.

Example Output:

CONTAINER ID  IMAGE                  COMMAND      CREATED         STATUS                       PORTS     NAMES
ea3519c89a9f  ubuntu:latest          bash         2 hours ago     Up 2 hours                             joyful_cray
cdfebe2c9d7a  nginx:alpine           nginx        3 hours ago     Exited (0) 1 hour ago                 fervent_goldwasser
d4afcaca46b7  redis                  redis        5 hours ago     Created                                sharp_neumann

Use Case 3: Show the Latest Created Container (Includes All States)

Code:

podman ps --latest

Motivation: Identifying the most recently created container is particularly useful when testing or developing applications. It helps users quickly retrieve information about the last added service or application within their infrastructure, which can be critical for debugging or continuing development work after a creation operation.

Explanation:

• --latest: This option narrows the scope to show only the last container created, regardless of its current state (running, exited, or created).

Example Output:

CONTAINER ID  IMAGE                COMMAND      CREATED        STATUS                       PORTS   NAMES
d4afcaca46b7  redis                redis        5 seconds ago  Created                              sharp_neumann

Use Case 4: Filter Containers that Contain a Substring in Their Name

Code:

podman ps --filter "name=name"

Motivation: In an environment with numerous containers, filtering by name allows users to directly access information about specific services, especially when container names incorporate aspects of their deployed applications or services. This specificity helps in efficiently managing and operating large-scale deployments.

Explanation:

• --filter: Introduces a key-value pair to narrow down the set of containers.
• "name=name": This key refers to searching for containers whose names include the specified substring name.

Example Output:

CONTAINER ID  IMAGE                COMMAND      CREATED         STATUS                   PORTS  NAMES
65ea2bf1c554  wordpress:latest     php-apache   3 days ago      Up 3 days                80/tcp obtain_name_feature

Use Case 5: Filter Containers that Share a Given Image as an Ancestor

Code:

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

Motivation: When deploying multi-environment setups or microservices architectures, it’s common for various containers to use the same image. Filtering by ancestor images is essential when needing to obtain statistics or perform operations on containers spawned from a certain image version.

Explanation:

• --filter: Used to apply conditional display of containers.
• "ancestor=image:tag": This condition matches all containers derived from a specific image and its tag (version), thus listing all containers sharing this commonality.

Example Output:

CONTAINER ID  IMAGE                COMMAND      CREATED         STATUS                   PORTS  NAMES
445f601c626d  alpine:3.12          sh           24 hours ago    Up 24 hours                    focused_wingate
cdfebe2c9d7a  alpine:3.12          apache-httpd 5 hours ago     Exited (0) 3 hours ago         stunning_hodgkin

Use Case 6: Filter Containers by Exit Status Code

Code:

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

Motivation: Analyzing containers by their exit codes can be crucial for debugging and forensics in program execution. Exit codes provide insight into why a container stopped, whether it was successful or due to an error, facilitating faster problem resolution.

Explanation:

• --all: List all containers regardless of their state to include those that have exited.
• --filter "exited=code": Narrows down the list to those containers that have terminated with the specified exit code (e.g., 0 for success).

Example Output:

CONTAINER ID  IMAGE                COMMAND      CREATED         STATUS                     PORTS  NAMES
cdfebe2c9d7a  nginx:alpine         nginx        1 week ago      Exited (0) a day ago             fervent_goldwasser

Use Case 7: Filter Containers by Status

Code:

podman ps --filter "status=status"

Motivation: Containers can exist in various states, such as created, running, paused, exited, etc. Filtering by status provides a quick method to obtain containers in a particular lifecycle phase, assisting in management tasks that depend on the container’s operational status.

Explanation:

• --filter: Applies a condition.
• "status=status": Specifies the target status to display, such as running, exited, paused, or created, allowing for focused troubleshooting or management.

Example Output:

CONTAINER ID  IMAGE                COMMAND      CREATED         STATUS                      PORTS  NAMES
45acbc3de763  node:14              npm start    24 hours ago    Paused                             serene_easley
e231c9a74d1f  httpd:2.4            httpd-foreg  6 days ago      Running                           agitated_mclaren

Use Case 8: Filter Containers that Mount a Specific Volume or Have a Volume Mounted in a Specific Path

Code:

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

Motivation: For containers that rely on external data via volumes, it’s critical to determine which containers are using particular volumes to prevent data inconsistencies and manage storage efficiently. This filter enables administrators to review volume usage across different containers.

Explanation:

• --filter "volume=path/to/directory": Lists containers based on the use of a specific path mounted as a volume.
• --format "table .ID\t.Image\t.Names\t.Mounts": Organizes the output into a table displaying container ID, image, name, and mount destinations for improved readability.

Example Output:

CONTAINER ID  IMAGE           NAMES               MOUNTS
4f739b1f3083  mysql:latest    amazing_hawking     /data:/var/lib/mysql
d09adb347b3f  postgres:alpine db-server-02        /mnt/db:/var/lib/postgresql/data

Conclusion

The podman ps command is a versatile tool that plays a crucial role in container management, allowing users to list and filter containers based on a wide range of criteria. Mastering this command empowers system administrators and developers to efficiently monitor and interact with containers, ensuring optimal operation within their environments. By offering options for filtering by container status, image ancestry, volume mounts, and more, podman ps provides detailed and tailored insights necessary for effective container ecosystem governance.