podman-ps

List Podman containers

TLDR

List currently running Podman containers

$ podman ps

List all Podman containers (running and stopped)

$ podman ps --all

Show the latest created container (includes all states)

$ podman ps --latest

Filter containers that contain a substring in their name

$ podman ps --filter "name=[name]"

Filter containers that share a given image as an ancestor

$ podman ps --filter "ancestor=[image]:[tag]"

Filter containers by exit status code

$ podman ps --all --filter "exited=[code]"

Filter containers by status (created, running, removing, paused, exited and dead)

$ podman ps --filter "status=[status]"

Filter containers that mount a specific volume or have a volume mounted in a specific path

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

-a, --all
    Display all containers, including exited ones. By default, only running containers are shown.

-l, --latest, --last
    Display the latest created container, regardless of its state.

-n, --no-trunc
    Don't truncate output. Show full container IDs, names, and command details.

-q, --quiet
    Only display numeric IDs of containers, useful for scripting.

-s, --size
    Display total file sizes of containers, including the size of the container's root filesystem and a virtual size.

-f, --filter filter
    Filter output based on conditions (e.g., status, name, image, id, ancestor).

--format format
    Pretty-print containers using a Go template for highly customized output.

-p, --pods
    Show containers that are part of a pod, indicating their associated pod ID.

--sort column
    Sort output by specified column name (e.g., 'id', 'name', 'status', 'created').

--sync
    Synchronize container state with storage. Ensures the displayed status is up-to-date.

DESCRIPTION

The podman-ps command is used to list Podman containers. By default, it displays only running containers. This command provides a quick overview of active containerized processes, including their ID, image, command, creation time, status, exposed ports, and assigned names. It serves as the primary utility for inspecting the current state of containers managed by Podman. Users familiar with Docker will find its functionality analogous to docker ps.

The output can be customized to show all containers (including exited ones), display file sizes, or be filtered and formatted for specific information, making it an indispensable tool for container management and troubleshooting.

CAVEATS

When using the --format option, constructing complex Go templates can be challenging and requires familiarity with Go template syntax. Filtering with --filter requires knowledge of available keys like status, name, or id, and invalid keys will be ignored. The --sync option can take time to complete if there are many containers or if the storage backend is slow, potentially delaying output.

OUTPUT COLUMNS

By default, podman-ps displays several columns: CONTAINER ID, IMAGE, COMMAND, CREATED, STATUS, PORTS, and NAMES. These columns provide essential information for quick identification and status checks of containers.

FILTERING EXAMPLES

You can filter the output using --filter. For instance, podman ps --filter status=exited shows only stopped containers. Multiple filters can be combined, such as podman ps --filter status=running --filter ancestor=myimage to refine results.

GO TEMPLATE FORMATTING

The --format option allows for highly customized output. For example, podman ps --format \"{{.ID}} {{.Names}}\" will display only the container ID and name. This uses Go template syntax, offering powerful formatting capabilities by accessing various container attributes.

HISTORY

podman-ps is a core command within the Podman project, which emerged as a daemonless alternative to Docker, focusing on OCI (Open Container Initiative) standards. Its design deliberately mirrors the well-known docker ps command, aiming for ease of transition for users migrating from Docker.

The command has been integral to Podman's evolution, providing immediate insight into the state of containers without requiring a background daemon, aligning with Podman's systemd-friendly and rootless container capabilities. Its continuous development reflects the community's commitment to robust and user-friendly container management.