github.com/netbrain/docker@v1.9.0-rc2/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=false Show all containers (default shows just running) 18 --before="" Show only container created before Id or Name 19 -f, --filter=[] Filter output based on conditions provided 20 --format=[] Pretty-print containers using a Go template 21 --help=false Print usage 22 -l, --latest=false Show the latest created container, include non-running 23 -n=-1 Show n last created containers, include non-running 24 --no-trunc=false Don't truncate output 25 -q, --quiet=false Only display numeric IDs 26 -s, --size=false Display total file sizes 27 --since="" Show created since Id or Name, include non-running 28 29 Running `docker ps --no-trunc` showing 2 linked containers. 30 31 $ docker ps 32 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 33 4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp 34 d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db 35 36 `docker ps` will show only running containers by default. To see all containers: 37 `docker ps -a` 38 39 `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. 40 41 ## Filtering 42 43 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more 44 than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`) 45 46 The currently supported filters are: 47 48 * id (container's id) 49 * label (`label=<key>` or `label=<key>=<value>`) 50 * name (container's name) 51 * exited (int - the code of exited containers. Only useful with `--all`) 52 * status (created|restarting|running|paused|exited) 53 * ancestor (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filters containers that were created from the given image or a descendant. 54 55 56 #### Label 57 58 The `label` filter matches containers based on the presence of a `label` alone or a `label` and a 59 value. 60 61 The following filter matches containers with the `color` label regardless of its value. 62 63 $ docker ps --filter "label=color" 64 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 65 673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley 66 d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani 67 68 The following filter matches containers with the `color` label with the `blue` value. 69 70 $ docker ps --filter "label=color=blue" 71 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 72 d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani 73 74 #### Name 75 76 The `name` filter matches on all or part of a container's name. 77 78 The following filter matches all containers with a name containing the `nostalgic_stallman` string. 79 80 $ docker ps --filter "name=nostalgic_stallman" 81 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 82 9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman 83 84 You can also filter for a substring in a name as this shows: 85 86 $ docker ps --filter "name=nostalgic" 87 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 88 715ebfcee040 busybox "top" 3 seconds ago Up 1 seconds i_am_nostalgic 89 9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman 90 673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley 91 92 #### Exited 93 94 The `exited` filter matches containers by exist status code. For example, to filter for containers 95 that have exited successfully: 96 97 $ docker ps -a --filter 'exited=0' 98 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 99 ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey 100 106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani 101 48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds 102 103 #### Status 104 105 The `status` filter matches containers by status. You can filter using `created`, `restarting`, `running`, `paused` and `exited`. For example, to filter for `running` containers: 106 107 $ docker ps --filter status=running 108 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 109 715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic 110 d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top 111 9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman 112 113 To filter for `paused` containers: 114 115 $ docker ps --filter status=paused 116 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 117 673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley 118 119 #### Ancestor 120 121 The `ancestor` filter matches containers based on its image or a descendant of it. The filter supports the 122 following image representation: 123 124 - image 125 - image:tag 126 - image:tag@digest 127 - short-id 128 - full-id 129 130 If you don't specify a `tag`, the `latest` tag is used. For example, to filter for containers that use the 131 latest `ubuntu` image: 132 133 $ docker ps --filter ancestor=ubuntu 134 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 135 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace 136 5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet 137 82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose 138 bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath 139 140 Match containers based on the `ubuntu-c1` image which, in this case, is a child of `ubuntu`: 141 142 $ docker ps --filter ancestor=ubuntu-c1 143 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 144 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace 145 146 Match containers based on the `ubuntu` version `12.04.5` image: 147 148 $ docker ps --filter ancestor=ubuntu:12.04.5 149 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 150 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose 151 152 The following matches containers based on the layer `d0e008c6cf02` or an image that have this layer 153 in it's layer stack. 154 155 $ docker ps --filter ancestor=d0e008c6cf02 156 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 157 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose 158 159 160 ## Formatting 161 162 The formatting option (`--format`) will pretty-print container output using a Go template. 163 164 Valid placeholders for the Go template are listed below: 165 166 Placeholder | Description 167 ---- | ---- 168 `.ID` | Container ID 169 `.Image` | Image ID 170 `.Command` | Quoted command 171 `.CreatedAt` | Time when the container was created. 172 `.RunningFor` | Elapsed time since the container was started. 173 `.Ports` | Exposed ports. 174 `.Status` | Container status. 175 `.Size` | Container disk size. 176 `.Names` | Container names. 177 `.Labels` | All labels assigned to the container. 178 `.Label` | Value of a specific label for this container. For example `{{.Label "com.docker.swarm.cpu"}}` 179 180 When using the `--format` option, the `ps` command will either output the data exactly as the template 181 declares or, when using the `table` directive, will include column headers as well. 182 183 The following example uses a template without headers and outputs the `ID` and `Command` 184 entries separated by a colon for all running containers: 185 186 $ docker ps --format "{{.ID}}: {{.Command}}" 187 a87ecb4f327c: /bin/sh -c #(nop) MA 188 01946d9d34d8: /bin/sh -c #(nop) MA 189 c1d3b0166030: /bin/sh -c yum -y up 190 41d50ecd2f57: /bin/sh -c #(nop) MA 191 192 To list all running containers with their labels in a table format you can use: 193 194 $ docker ps --format "table {{.ID}}\t{{.Labels}}" 195 CONTAINER ID LABELS 196 a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd 197 01946d9d34d8 198 c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6 199 41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd