diff --git a/docs/reference/commandline/ps.md b/docs/reference/commandline/ps.md index 63aaa56985..48ef2ce13e 100644 --- a/docs/reference/commandline/ps.md +++ b/docs/reference/commandline/ps.md @@ -38,15 +38,24 @@ Options: Running `docker ps --no-trunc` showing 2 linked containers. - $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp - d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db +```bash +$ docker ps -`docker ps` will show only running containers by default. To see all containers: -`docker ps -a` +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp +d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db +``` -`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. +The `docker ps` command only shows running containers by default. To see all +containers, use the `-a` (or `--all`) flag: + +```bash +$ docker ps -a +``` + +`docker ps` groups exposed ports into a single range if possible. E.g., a +container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in +the `PORTS` column. ## Filtering @@ -74,16 +83,22 @@ value. The following filter matches containers with the `color` label regardless of its value. - $ docker ps --filter "label=color" - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley - d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani +```bash +$ docker ps --filter "label=color" + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley +d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani +``` The following filter matches containers with the `color` label with the `blue` value. - $ docker ps --filter "label=color=blue" - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani +```bash +$ docker ps --filter "label=color=blue" + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani +``` #### Name @@ -91,49 +106,66 @@ The `name` filter matches on all or part of a container's name. The following filter matches all containers with a name containing the `nostalgic_stallman` string. - $ docker ps --filter "name=nostalgic_stallman" - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman +```bash +$ docker ps --filter "name=nostalgic_stallman" + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman +``` You can also filter for a substring in a name as this shows: - $ docker ps --filter "name=nostalgic" - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 715ebfcee040 busybox "top" 3 seconds ago Up 1 seconds i_am_nostalgic - 9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman - 673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley +```bash +$ docker ps --filter "name=nostalgic" + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +715ebfcee040 busybox "top" 3 seconds ago Up 1 seconds i_am_nostalgic +9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman +673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley +``` #### Exited -The `exited` filter matches containers by exist status code. For example, to filter for containers -that have exited successfully: +The `exited` filter matches containers by exist status code. For example, to +filter for containers that have exited successfully: - $ docker ps -a --filter 'exited=0' - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey - 106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani - 48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds +```bash +$ docker ps -a --filter 'exited=0' + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey +106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani +48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds +``` #### Status -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: +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: - $ docker ps --filter status=running - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic - d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top - 9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman +```bash +$ docker ps --filter status=running + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic +d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top +9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman +``` To filter for `paused` containers: - $ docker ps --filter status=paused - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley +```bash +$ docker ps --filter status=paused + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley +``` #### Ancestor -The `ancestor` filter matches containers based on its image or a descendant of it. The filter supports the -following image representation: +The `ancestor` filter matches containers based on its image or a descendant of +it. The filter supports the following image representation: - image - image:tag @@ -141,74 +173,99 @@ following image representation: - short-id - full-id -If you don't specify a `tag`, the `latest` tag is used. For example, to filter for containers that use the -latest `ubuntu` image: +If you don't specify a `tag`, the `latest` tag is used. For example, to filter +for containers that use the latest `ubuntu` image: - $ docker ps --filter ancestor=ubuntu - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace - 5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet - 82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose - bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath +```bash +$ docker ps --filter ancestor=ubuntu -Match containers based on the `ubuntu-c1` image which, in this case, is a child of `ubuntu`: +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace +5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet +82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose +bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath +``` - $ docker ps --filter ancestor=ubuntu-c1 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace +Match containers based on the `ubuntu-c1` image which, in this case, is a child +of `ubuntu`: + +```bash +$ docker ps --filter ancestor=ubuntu-c1 + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace +``` Match containers based on the `ubuntu` version `12.04.5` image: - $ docker ps --filter ancestor=ubuntu:12.04.5 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose +```bash +$ docker ps --filter ancestor=ubuntu:12.04.5 -The following matches containers based on the layer `d0e008c6cf02` or an image that have this layer -in it's layer stack. +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose +``` - $ docker ps --filter ancestor=d0e008c6cf02 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose +The following matches containers based on the layer `d0e008c6cf02` or an image +that have this layer in it's layer stack. + +```bash +$ docker ps --filter ancestor=d0e008c6cf02 + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose +``` #### Before -The `before` filter shows only containers created before the container with given id or name. For example, -having these containers created: +The `before` filter shows only containers created before the container with +given id or name. For example, having these containers created: - $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9c3527ed70ce busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky - 4aace5031105 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton - 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat +```bash +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +9c3527ed70ce busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky +4aace5031105 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton +6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat +``` Filtering with `before` would give: - $ docker ps -f before=9c3527ed70ce - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 4aace5031105 busybox "top" About a minute ago Up About a minute focused_hamilton - 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat +```bash +$ docker ps -f before=9c3527ed70ce + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +4aace5031105 busybox "top" About a minute ago Up About a minute focused_hamilton +6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat +``` #### Since -The `since` filter shows only containers created since the container with given id or name. For example, -with the same containers as in `before` filter: +The `since` filter shows only containers created since the container with given +id or name. For example, with the same containers as in `before` filter: - $ docker ps -f since=6e63f6ff38b0 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9c3527ed70ce busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky - 4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton +```bash +$ docker ps -f since=6e63f6ff38b0 + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +9c3527ed70ce busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky +4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton +``` #### Volume -The `volume` filter shows only containers that mount a specific volume or have a volume mounted in a specific path: +The `volume` filter shows only containers that mount a specific volume or have +a volume mounted in a specific path: - $ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" - CONTAINER ID MOUNTS - 9c3527ed70ce remote-volume +```bash +$ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" +CONTAINER ID MOUNTS +9c3527ed70ce remote-volume - $ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}" - CONTAINER ID MOUNTS - 9c3527ed70ce remote-volume +$ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}" +CONTAINER ID MOUNTS +9c3527ed70ce remote-volume +``` #### Network @@ -223,6 +280,7 @@ $ docker run -d --net=net1 --name=test1 ubuntu top $ docker run -d --net=net2 --name=test2 ubuntu top $ docker ps --filter network=net1 + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 ``` @@ -233,51 +291,61 @@ the network id as a filter; ```bash $ docker network inspect --format "{{.ID}}" net1 + 8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 $ docker ps --filter network=8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 ``` ## Formatting -The formatting option (`--format`) will pretty-print container output using a Go template. +The formatting option (`--format`) pretty-prints container output using a Go +template. Valid placeholders for the Go template are listed below: -Placeholder | Description ----- | ---- -`.ID` | Container ID -`.Image` | Image ID -`.Command` | Quoted command -`.CreatedAt` | Time when the container was created. +Placeholder | Description +--------------|---------------------------------------------------------------------------------------------------- +`.ID` | Container ID +`.Image` | Image ID +`.Command` | Quoted command +`.CreatedAt` | Time when the container was created. `.RunningFor` | Elapsed time since the container was started. -`.Ports` | Exposed ports. -`.Status` | Container status. -`.Size` | Container disk size. -`.Names` | Container names. -`.Labels` | All labels assigned to the container. -`.Label` | Value of a specific label for this container. For example `{{.Label "com.docker.swarm.cpu"}}` -`.Mounts` | Names of the volumes mounted in this container. +`.Ports` | Exposed ports. +`.Status` | Container status. +`.Size` | Container disk size. +`.Names` | Container names. +`.Labels` | All labels assigned to the container. +`.Label` | Value of a specific label for this container. For example `'{{.Label "com.docker.swarm.cpu"}}'` +`.Mounts` | Names of the volumes mounted in this container. -When using the `--format` option, the `ps` command will either output the data exactly as the template -declares or, when using the `table` directive, will include column headers as well. +When using the `--format` option, the `ps` command will either output the data +exactly as the template declares or, when using the `table` directive, includes +column headers as well. -The following example uses a template without headers and outputs the `ID` and `Command` -entries separated by a colon for all running containers: +The following example uses a template without headers and outputs the `ID` and +`Command` entries separated by a colon for all running containers: - $ docker ps --format "{{.ID}}: {{.Command}}" - a87ecb4f327c: /bin/sh -c #(nop) MA - 01946d9d34d8: /bin/sh -c #(nop) MA - c1d3b0166030: /bin/sh -c yum -y up - 41d50ecd2f57: /bin/sh -c #(nop) MA +```bash +$ docker ps --format "{{.ID}}: {{.Command}}" + +a87ecb4f327c: /bin/sh -c #(nop) MA +01946d9d34d8: /bin/sh -c #(nop) MA +c1d3b0166030: /bin/sh -c yum -y up +41d50ecd2f57: /bin/sh -c #(nop) MA +``` To list all running containers with their labels in a table format you can use: - $ docker ps --format "table {{.ID}}\t{{.Labels}}" - CONTAINER ID LABELS - a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd - 01946d9d34d8 - c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6 - 41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd +```bash +$ docker ps --format "table {{.ID}}\t{{.Labels}}" + +CONTAINER ID LABELS +a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd +01946d9d34d8 +c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6 +41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd +```