podman-ps(1)

📦
version 6.1.4 · 6 versions
, in arch rolling

💅 podman-ps(1) 💅

General Commands Manual — yes bestie, we're reading the manual manual today 🎀

✨ NAME ✨

podman-ps — print out information about containers 👀

🦋 SYNOPSIS 🦋

podman ps [options]

podman container ps [options]

podman container list [options]

podman container ls [options]

Four whole ways to say the same thing, and honestly? iconic. pick your fave 🫶

🌸 DESCRIPTION 🌸

okay so podman ps lists the containers that are running on your system, periodt. want the whole picture though? that's what the --all flag is for — it shows you everything, not just the live ones. no cap 💅

by default, here's what it spills for you:

  • container id
  • the name of the image the container is using
  • the COMMAND the container is executing
  • the time the container was created
  • the status of the container
  • port mappings the container is using
  • alternative names for the container

like, a full little vibe check on every container. obsessed 😭

⭐ OPTIONS ⭐

💖 --all, -a

show all the containers — default is only the running ones, so if you're like "where did my exited containers go??" this is your girl ✨

note bestie: Podman shares containers storage with other tools such as Buildah and CRI-O. in some cases these external containers might also exist in the same storage. use the --external option to see these external containers. external containers show the 'storage' status. 🫶

🧚 --external

display external containers that are not controlled by Podman but are stored in containers storage 👑 these external containers are generally created via other container technology such as Buildah or CRI-O, and they may depend on the same container images that Podman is also using. external containers are denoted with either a 'buildah' or 'storage' in the COMMAND and STATUS column of the ps output.

heads up: the restart-policy, volume, health, and annotation filters are not applicable for external containers. 🙈

🔥 --filter, -f=_filter_

filter what containers ps shows you. multiple filters can be given with multiple uses of the --filter flag 🎀 filters with the same key work inclusive, with the only exception being label, which is exclusive. filters with different keys always work exclusive. iykyk 💅

here's every valid filter, no gatekeeping:

  • id — [ID] Container's ID (CID prefix match by default; accepts regex)
  • name — [Name] Container's name (accepts regex)
  • annotation — [Key] or [Key=Value] Annotation assigned to a container
  • annotation! — [Key] or [Key=Value] Annotation NOT assigned to a container
  • label — [Key] or [Key=Value] Label assigned to a container
  • label! — [Key] or [Key=Value] Label NOT assigned to a container
  • exited — [Int] Container's exit code
  • status — [Status] Container's status: 'created', 'initialized', 'running', 'stopped', 'paused', 'exited', 'removing', 'stopping', 'unknown'
  • ancestor — [ImageName] Image or descendant used to create container (accepts regex)
  • before — [ID] or [Name] Containers created before this container
  • since — [ID] or [Name] Containers created since this container
  • volume — [VolumeName] or [MountpointDestination] Volume mounted in container
  • health — [Status] healthy or unhealthy
  • pod — [Pod] name or full or partial ID of pod
  • network — [Network] name or full ID of network
  • restart-policy — [Policy] Container's restart policy (e.g., 'no', 'on-failure', 'always', 'unless-stopped')
  • until — [DateTime] Containers created before the given duration or time.
  • command — [Command] the command the container is executing, only argv[0] is taken
  • should-start-on-boot — [Bool] Containers that need to be restarted after system reboot. True for containers with restart policy 'always', or 'unless-stopped' that were not explicitly stopped by the user

🎀 --format=_format_

pretty-print containers to JSON or using a Go template ✨

valid placeholders for the Go template are listed below:

(…and that's where part 1 wraps, bestie — the placeholder list is coming right up 💜)

🎀 the placeholder table (for when u wanna format ur own output)

okay so these are the placeholders u can drop into ur format string — each one pulls out a different lil fact about the container. left column = the placeholder, right column = what it gives u. periodt. 💅

  • .AutoRemove — If true, containers are removed on exit
  • .CIDFile — Container ID File
  • .Command — Quoted command used
  • .Created ... — Creation time for container, Y-M-D H:M:S
  • .CreatedAt — Creation time for container (same as above)
  • .CreatedHuman — Creation time, relative
  • .ExitCode — Container exit code
  • .Exited — "true" if container has exited
  • .ExitedAt — Time (epoch seconds) that container exited
  • .ExposedPorts ... — Map of exposed ports on this container
  • .ID — Container ID
  • .Image — Image Name/ID
  • .ImageID — Image ID
  • .IsInfra — "true" if infra container
  • .Label string — Specified label of the container
  • .Labels — All the labels assigned to the container
  • .Mounts — Volumes mounted in the container
  • .Names — Name of container
  • .Networks — Show all networks connected to the container
  • .Pid — Process ID on host system
  • .Pod — Pod the container is associated with (SHA)
  • .PodName — PodName of the container
  • .Ports — Forwarded and exposed ports
  • .Restarts — Display the container restart count
  • .RunningFor — Time elapsed since container was started
  • .Size — Size of container
  • .StartedAt — Time (epoch seconds) the container started
  • .State — Human-friendly description of ctr state
  • .Status — Status of container

✨ OPTIONS (the rest of the menu, bestie) ✨

  • --help, -h — Print usage statement. ur lil "what do i even type" rescue button 🫶
  • --last, -n — Print the n last created containers, all states included. so if u pass -n 5 ur getting the five most recent babies, no matter what state they're in 💫
  • --latest, -l — Show the latest container created (all states). heads up tho: this option is not available with the remote Podman client — that includes Mac and Windows machines, WSL2 excluded 👀
  • --namespace, --ns — Display namespace information. get the whole namespace tea ☕
  • --no-trunc — Do not truncate the output (default false). so nothing gets chopped off, u see the full unedited version, no cuts ✂️🚫
  • --noheading — Omit the table headings from the listing of containers. just the rows, no header row, minimal queen behavior 👑
  • --pod, -p — Display the pods the containers are associated with. pods get a shoutout too 🫘
  • --quiet, -q — Print the numeric IDs of the containers only. no names, no noise, just IDs, and honestly? iconic 😌
  • --size, -s — Display the total file size. numbers on numbers 📏
  • --sort=created — Sort by command, created, id, image, names, runningfor, size, or status.
⚠️ bestie read this one fr: choosing size sorts by size of rootFs, not alphabetically like the rest of the options. so that one's the odd one out, lowkey doing its own thing 💀
  • --sync — Force a sync of container state with the OCI runtime. In some cases, a container's state in the runtime can become out of sync with Podman's state. This updates Podman's state based on what the OCI runtime reports. Forcibly syncing is much slower, but can resolve inconsistent state issues. 🩹
like hitting refresh on a group chat that's glitching — takes a sec, but everything lines back up again.
  • --watch, -w — Refresh the output with current containers on an interval in seconds. so it just keeps updating itself, live, the way that it stays current without u lifting a finger ✨👁️

✨ EXAMPLES ✨

Okay bestie, this is the fun part — real commands, real output, all of it. Let's go 🌸

🎀 List running containers

Just the ones that are, like, actually up right now:

$ podman ps
CONTAINER ID  IMAGE                            COMMAND    CREATED        STATUS        PORTS                                                   NAMES
4089df24d4f3  docker.io/library/centos:latest  /bin/bash  2 minutes ago  Up 2 minutes  0.0.0.0:80->8080/tcp, 0.0.0.0:2000-2006->2000-2006/tcp  manyports
92f58933c28c  docker.io/library/centos:latest  /bin/bash  3 minutes ago  Up 3 minutes  192.168.99.100:1000-1006->1000-1006/tcp                 zen_sanderson

🦋 List all containers

Every single one, running or not — no cap:

$ podman ps -a
CONTAINER ID   IMAGE         COMMAND         CREATED       STATUS                    PORTS     NAMES
02f65160e14ca  redis:alpine  "redis-server"  19 hours ago  Exited (-1) 19 hours ago  6379/tcp  k8s_podsandbox1-redis_podsandbox1_redhat.test.crio_redhat-test-crio_0
69ed779d8ef9f  redis:alpine  "redis-server"  25 hours ago  Created                   6379/tcp  k8s_container1_podsandbox1_redhat.test.crio_redhat-test-crio_1

💅 List all containers including their size

Heads up though — this one can take longer, because Podman has to actually go calculate the size from the file system. It's doing math for you, be nice 😭

$ podman ps -a -s
CONTAINER ID   IMAGE         COMMAND         CREATED       STATUS                    PORTS     NAMES                                                                  SIZE
02f65160e14ca  redis:alpine  "redis-server"  20 hours ago  Exited (-1) 20 hours ago  6379/tcp  k8s_podsandbox1-redis_podsandbox1_redhat.test.crio_redhat-test-crio_0  27.49 MB
69ed779d8ef9f  redis:alpine  "redis-server"  25 hours ago  Created                   6379/tcp  k8s_container1_podsandbox1_redhat.test.crio_redhat-test-crio_1         27.49 MB

🧚 List all containers with a custom Go format

Running or not, and you pick exactly what shows up. Main character formatting energy ✨

$ podman ps -a --format "{{.ID}}  {{.Image}}  {{.Labels}}  {{.Mounts}}"
02f65160e14ca  redis:alpine  tier=backend  proc,tmpfs,devpts,shm,mqueue,sysfs,cgroup,/var/run/,/var/run/
69ed779d8ef9f  redis:alpine  batch=no,type=small  proc,tmpfs,devpts,shm,mqueue,sysfs,cgroup,/var/run/,/var/run/

🌈 List all containers and display their namespaces

All the namespace tea, laid out in columns:

$ podman ps --ns -a
CONTAINER ID    NAMES                                                                   PID     CGROUP       IPC          MNT          NET          PIDNS        USER         UTS
3557d882a82e3   k8s_container2_podsandbox1_redhat.test.crio_redhat-test-crio_1          29910   4026531835   4026532585   4026532593   4026532508   4026532595   4026531837   4026532594
09564cdae0bec   k8s_container1_podsandbox1_redhat.test.crio_redhat-test-crio_1          29851   4026531835   4026532585   4026532590   4026532508   4026532592   4026531837   4026532591
a31ebbee9cee7   k8s_podsandbox1-redis_podsandbox1_redhat.test.crio_redhat-test-crio_0   29717   4026531835   4026532585   4026532587   4026532508   4026532589   4026531837   4026532588

🍓 List all containers including size, sorted by names

Same energy, but alphabetically ordered by name. Organized queen 👑

$ podman ps -a --size --sort names
CONTAINER ID   IMAGE         COMMAND         CREATED       STATUS                    PORTS     NAMES
69ed779d8ef9f  redis:alpine  "redis-server"  25 hours ago  Created                   6379/tcp  k8s_container1_podsandbox1_redhat.test.crio_redhat-test-crio_1
02f65160e14ca  redis:alpine  "redis-server"  19 hours ago  Exited (-1) 19 hours ago  6379/tcp  k8s_podsandbox1-redis_podsandbox1_redhat.test.crio_redhat-test-crio_0

🔥 List all external containers

These are the ones other tools made, not Podman. Outsiders, but we love them 🫶

$ podman ps --external -a
CONTAINER ID  IMAGE                             COMMAND  CREATED      STATUS  PORTS  NAMES
69ed779d8ef9f  redis:alpine  "redis-server"  25 hours ago  Created                   6379/tcp  k8s_container1_podsandbox1_redhat.test.crio_redhat-test-crio_1
38a8a78596f9  docker.io/library/busybox:latest  buildah  2 hours ago  storage        busybox-working-container
fd7b786b5c32  docker.io/library/alpine:latest   buildah  2 hours ago  storage        alpine-working-container
f78620804e00  scratch                           buildah  2 hours ago  storage        working-container

🌸 List containers with their associated pods

Who belongs to which pod — the group chat roster 💬

$ podman ps --pod
CONTAINER ID  IMAGE                            COMMAND    CREATED        STATUS        PORTS     NAMES               POD ID        PODNAME
4089df24d4f3  docker.io/library/nginx:latest  nginx      2 minutes ago  Up 2 minutes  80/tcp    webserver           1234567890ab  web-pod
92f58933c28c  docker.io/library/redis:latest  redis      3 minutes ago  Up 3 minutes  6379/tcp  cache               1234567890ab  web-pod
a1b2c3d4e5f6  docker.io/library/centos:latest /bin/bash  1 minute ago   Up 1 minute             standalone-container

💜 List all containers with pod info, even the pod-less ones

Same thing but -a, so the ones with no pod at all show up too. They're valid, they're just solo 😌

$ podman ps -a --pod
CONTAINER ID  IMAGE                            COMMAND    CREATED        STATUS                    PORTS     NAMES                POD ID        PODNAME
4089df24d4f3  docker.io/library/nginx:latest  nginx      2 minutes ago  Up 2 minutes              80/tcp    webserver            1234567890ab  web-pod
92f58933c28c  docker.io/library/redis:latest  redis      3 minutes ago  Up 3 minutes              6379/tcp  cache                1234567890ab  web-pod
69ed779d8ef9f redis:alpine                     redis      25 hours ago   Exited (0) 25 hours ago   6379/tcp  old-cache            5678901234cd  old-pod
a1b2c3d4e5f6  docker.io/library/centos:latest /bin/bash  1 minute ago   Up 1 minute                         standalone-container

🎀 Filter containers by pod name

$ podman ps --filter pod=web-pod
CONTAINER ID  IMAGE                            COMMAND    CREATED        STATUS        PORTS     NAMES
4089df24d4f3  docker.io/library/nginx:latest  nginx      2 minutes ago  Up 2 minutes  80/tcp    webserver
92f58933c28c  docker.io/library/redis:latest  redis      3 minutes ago  Up 3 minutes  6379/tcp  cache

✨ Filter containers by Status

Only the running ones, please and thank you:

$ podman ps --filter status=running
CONTAINER ID  IMAGE                             COMMAND               CREATED         STATUS                  PORTS                           NAMES
ff660efda598  docker.io/library/nginx:latest    nginx -g daemon o...  3 minutes ago   Up 3 minutes            0.0.0.0:8080->80/tcp            webserver
5693e934f4c6  docker.io/library/redis:latest    redis-server          3 minutes ago   Up 3 minutes            6379/tcp                        cache
2b271d67dbb6                                                          3 minutes ago   Up 3 minutes            0.0.0.0:9090->80/tcp            463241862e7e-infra
23f99674da1c  docker.io/library/nginx:latest    nginx -g daemon o...  3 minutes ago   Up 3 minutes            0.0.0.0:9090->80/tcp            pod-nginx
62180adfbd42  docker.io/library/redis:latest    redis-server          3 minutes ago   Up 3 minutes            0.0.0.0:9090->80/tcp, 6379/tcp  pod-redis
5e3694604817  quay.io/centos/centos:latest      sleep 300             3 minutes ago   Up 3 minutes                                            centos-test
af3d8b3f5471  docker.io/library/busybox:latest  sleep 1000            3 minutes ago   Up 3 minutes                                            test-dev
b6ee47492b64  docker.io/library/nginx:latest    nginx -g daemon o...  3 minutes ago   Up 3 minutes (healthy)  80/tcp                          healthy-nginx
db75e6c397db  docker.io/library/busybox:latest  sleep 300             23 seconds ago  Up 23 seconds                                         test-volume-container

And the exited girlies, with -a in the mix:

$ podman ps -a --filter status=exited
CONTAINER ID  IMAGE                            COMMAND     CREATED        STATUS                    PORTS                NAMES
94f211cc6e36  docker.io/library/alpine:latest  sleep 1     4 minutes ago  Exited (0) 4 minutes ago                       old-alpine
75a800cb848a  docker.io/library/mysql:latest   mysqld      3 minutes ago  Exited (1) 3 minutes ago  3306/tcp, 33060/tcp  db-container
2d9b3a94e31e  docker.io/library/nginx:latest   nginx       3 minutes ago  Exited (0) 3 minutes ago  80/tcp               nginx-cmd

🦋 Filter containers by name

$ podman ps --filter name=webserver
CONTAINER ID  IMAGE                           COMMAND               CREATED        STATUS        PORTS                 NAMES
ff660efda598  docker.io/library/nginx:latest  nginx -g daemon o...  3 minutes ago  Up 3 minutes  0.0.0.0:8080->80/tcp  webserver

💅 Filter containers by label

$ podman ps --filter label=app=frontend
CONTAINER ID  IMAGE                           COMMAND               CREATED        STATUS        PORTS                 NAMES
ff660efda598  docker.io/library/nginx:latest  nginx -g daemon o...  3 minutes ago  Up 3 minutes  0.0.0.0:8080->80/tcp  webserver

🧚 Filter containers by annotation

Yes, annotations are a whole separate thing from labels. Yes, you will mix them up. It's fine 💀

$ podman ps --filter annotation=io.podman.annotations.autoremove=false
CONTAINER ID  IMAGE                             COMMAND     CREATED        STATUS        PORTS       NAMES
5e3694604817  quay.io/centos/centos:latest      sleep 300   3 minutes ago  Up 3 minutes              centos-test

🍓 Filter containers by volume

$ podman ps --filter volume=mydata
CONTAINER ID  IMAGE                             COMMAND     CREATED         STATUS         PORTS       NAMES
db75e6c397db  docker.io/library/busybox:latest  sleep 300   42 seconds ago  Up 42 seconds              test-volume-container

🌈 Filter containers by network

$ podman ps --filter network=web-net
CONTAINER ID  IMAGE                         COMMAND     CREATED        STATUS        PORTS       NAMES
5e3694604817  quay.io/centos/centos:latest  sleep 300   3 minutes ago  Up 3 minutes              centos-test

🔥 Filter containers that need a restart after a system reboot

The ones that are like "okay I got rebooted, put me back in coach" 🫡

$ podman ps -a --filter should-start-on-boot=true
CONTAINER ID  IMAGE                           COMMAND               CREATED        STATUS                    PORTS                 NAMES
ff660efda598  docker.io/library/nginx:latest  nginx -g daemon o...  3 minutes ago  Up 3 minutes              0.0.0.0:8080->80/tcp  webserver
5693e934f4c6  docker.io/library/redis:latest  redis-server          3 minutes ago  Exited (0) 3 minutes ago  6379/tcp              cache

👑 Custom format for container and pod info

Look at how cute this reads — sentences, basically:

$ podman ps --format "{{.Names}} is in pod {{.PodName}} ({{.Pod}})"
webserver is in pod web-pod (1234567890ab)
cache is in pod web-pod (1234567890ab)
standalone-container is in pod  ()

(Yeah that last one has empty parens — that container isn't in a pod, it's just living its truth 💖)

🌈 SEE ALSO 🌈

💜 HISTORY 💜

Originally written August 2017 by the icon herself, Urvashi Mohnani — umohnani@redhat.com ⟨mailto:umohnani@redhat.com⟩ 🫶

And that's the whole podman-ps(1) man page, bestie — source and all, from the official Podman docs straight to your terminal. Go forth and ps responsibly, ily, bye 💅✨🎀

📦 where this page comes from