github.com/45cali/docker@v1.11.1/docs/reference/commandline/ps.md (about) 1 <!--[metadata]> 2 +++ 3 title = "ps" 4 description = "The ps command description and usage" 5 keywords = ["container, running, list"] 6 [menu.main] 7 parent = "smn_cli" 8 +++ 9 <![end-metadata]--> 10 11 # ps 12 13 Usage: docker ps [OPTIONS] 14 15 List containers 16 17 -a, --all Show all containers (default shows just running) 18 -f, --filter=[] Filter output based on these conditions: 19 - exited=<int> an exit code of <int> 20 - label=<key> or label=<key>=<value> 21 - status=(created|restarting|running|paused|exited) 22 - name=<string> a container's name 23 - id=<ID> a container's ID 24 - before=(<container-name>|<container-id>) 25 - since=(<container-name>|<container-id>) 26 - ancestor=(<image-name>[:tag]|<image-id>|<image@digest>) - containers created from an image or a descendant. 27 - volume=(<volume-name>|<mount-point>) 28 --format=[] Pretty-print containers using a Go template 29 --help Print usage 30 -l, --latest Show the latest created container (includes all states) 31 -n=-1 Show n last created containers (includes all states) 32 --no-trunc Don't truncate output 33 -q, --quiet Only display numeric IDs 34 -s, --size Display total file sizes 35 36 Running `docker ps --no-trunc` showing 2 linked containers. 37 38 $ docker ps 39 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 40 4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp 41 d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db 42 43 `docker ps` will show only running containers by default. To see all containers: 44 `docker ps -a` 45 46 `docker ps` will group exposed ports into a single range if possible. E.g., a container that exposes TCP ports `100, 101, 102` will display `100-102/tcp` in the `PORTS` column. 47 48 ## Filtering 49 50 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more 51 than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`) 52 53 The currently supported filters are: 54 55 * id (container's id) 56 * label (`label=<key>` or `label=<key>=<value>`) 57 * name (container's name) 58 * exited (int - the code of exited containers. Only useful with `--all`) 59 * status (created|restarting|running|paused|exited|dead) 60 * ancestor (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filters containers that were created from the given image or a descendant. 61 * before (container's id or name) - filters containers created before given id or name 62 * since (container's id or name) - filters containers created since given id or name 63 * isolation (default|process|hyperv) (Windows daemon only) 64 * volume (volume name or mount point) - filters containers that mount volumes. 65 66 67 #### Label 68 69 The `label` filter matches containers based on the presence of a `label` alone or a `label` and a 70 value. 71 72 The following filter matches containers with the `color` label regardless of its value. 73 74 $ docker ps --filter "label=color" 75 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 76 673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley 77 d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani 78 79 The following filter matches containers with the `color` label with the `blue` value. 80 81 $ docker ps --filter "label=color=blue" 82 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 83 d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani 84 85 #### Name 86 87 The `name` filter matches on all or part of a container's name. 88 89 The following filter matches all containers with a name containing the `nostalgic_stallman` string. 90 91 $ docker ps --filter "name=nostalgic_stallman" 92 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 93 9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman 94 95 You can also filter for a substring in a name as this shows: 96 97 $ docker ps --filter "name=nostalgic" 98 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 99 715ebfcee040 busybox "top" 3 seconds ago Up 1 seconds i_am_nostalgic 100 9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman 101 673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley 102 103 #### Exited 104 105 The `exited` filter matches containers by exist status code. For example, to filter for containers 106 that have exited successfully: 107 108 $ docker ps -a --filter 'exited=0' 109 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 110 ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey 111 106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani 112 48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds 113 114 #### Status 115 116 The `status` filter matches containers by status. You can filter using `created`, `restarting`, `running`, `paused`, `exited` and `dead`. For example, to filter for `running` containers: 117 118 $ docker ps --filter status=running 119 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 120 715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic 121 d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top 122 9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman 123 124 To filter for `paused` containers: 125 126 $ docker ps --filter status=paused 127 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 128 673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley 129 130 #### Ancestor 131 132 The `ancestor` filter matches containers based on its image or a descendant of it. The filter supports the 133 following image representation: 134 135 - image 136 - image:tag 137 - image:tag@digest 138 - short-id 139 - full-id 140 141 If you don't specify a `tag`, the `latest` tag is used. For example, to filter for containers that use the 142 latest `ubuntu` image: 143 144 $ docker ps --filter ancestor=ubuntu 145 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 146 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace 147 5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet 148 82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose 149 bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath 150 151 Match containers based on the `ubuntu-c1` image which, in this case, is a child of `ubuntu`: 152 153 $ docker ps --filter ancestor=ubuntu-c1 154 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 155 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace 156 157 Match containers based on the `ubuntu` version `12.04.5` image: 158 159 $ docker ps --filter ancestor=ubuntu:12.04.5 160 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 161 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose 162 163 The following matches containers based on the layer `d0e008c6cf02` or an image that have this layer 164 in it's layer stack. 165 166 $ docker ps --filter ancestor=d0e008c6cf02 167 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 168 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose 169 170 #### Before 171 172 The `before` filter shows only containers created before the container with given id or name. For example, 173 having these containers created: 174 175 $ docker ps 176 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 177 9c3527ed70ce busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky 178 4aace5031105 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton 179 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat 180 181 Filtering with `before` would give: 182 183 $ docker ps -f before=9c3527ed70ce 184 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 185 4aace5031105 busybox "top" About a minute ago Up About a minute focused_hamilton 186 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat 187 188 #### Since 189 190 The `since` filter shows only containers created since the container with given id or name. For example, 191 with the same containers as in `before` filter: 192 193 $ docker ps -f since=6e63f6ff38b0 194 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 195 9c3527ed70ce busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky 196 4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton 197 198 #### Volume 199 200 The `volume` filter shows only containers that mount a specific volume or have a volume mounted in a specific path: 201 202 $ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" 203 CONTAINER ID MOUNTS 204 9c3527ed70ce remote-volume 205 206 $ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}" 207 CONTAINER ID MOUNTS 208 9c3527ed70ce remote-volume 209 210 211 ## Formatting 212 213 The formatting option (`--format`) will pretty-print container output using a Go template. 214 215 Valid placeholders for the Go template are listed below: 216 217 Placeholder | Description 218 ---- | ---- 219 `.ID` | Container ID 220 `.Image` | Image ID 221 `.Command` | Quoted command 222 `.CreatedAt` | Time when the container was created. 223 `.RunningFor` | Elapsed time since the container was started. 224 `.Ports` | Exposed ports. 225 `.Status` | Container status. 226 `.Size` | Container disk size. 227 `.Names` | Container names. 228 `.Labels` | All labels assigned to the container. 229 `.Label` | Value of a specific label for this container. For example `{{.Label "com.docker.swarm.cpu"}}` 230 `.Mounts` | Names of the volumes mounted in this container. 231 232 When using the `--format` option, the `ps` command will either output the data exactly as the template 233 declares or, when using the `table` directive, will include column headers as well. 234 235 The following example uses a template without headers and outputs the `ID` and `Command` 236 entries separated by a colon for all running containers: 237 238 $ docker ps --format "{{.ID}}: {{.Command}}" 239 a87ecb4f327c: /bin/sh -c #(nop) MA 240 01946d9d34d8: /bin/sh -c #(nop) MA 241 c1d3b0166030: /bin/sh -c yum -y up 242 41d50ecd2f57: /bin/sh -c #(nop) MA 243 244 To list all running containers with their labels in a table format you can use: 245 246 $ docker ps --format "table {{.ID}}\t{{.Labels}}" 247 CONTAINER ID LABELS 248 a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd 249 01946d9d34d8 250 c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6 251 41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd