ps.md 15 KB
ps
Usage: docker ps [OPTIONS]
List containers
Options:
-a, --all Show all containers (default shows just running)
-f, --filter value Filter output based on conditions provided (default [])
- exited=<int> an exit code of <int>
- label=<key> or label=<key>=<value>
- status=(created|restarting|running|paused|exited)
- name=<string> a container's name
- id=<ID> a container's ID
- before=(<container-name>|<container-id>)
- since=(<container-name>|<container-id>)
- ancestor=(<image-name>[:tag]|<image-id>|<image@digest>)
containers created from an image or a descendant.
--format string Pretty-print containers using a Go template
--help Print usage
-n, --last int Show n last created containers (includes all states) (default -1)
-l, --latest Show the latest created container (includes all states)
--no-trunc Don't truncate output
-q, --quiet Only display numeric IDs
-s, --size Display total file sizes
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
The docker ps command only shows running containers by default. To see all
containers, use the -a (or --all) flag:
$ 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
The filtering flag (-f or --filter) format is a key=value pair. If there is more
than one filter, then pass multiple flags (e.g. --filter "foo=bar" --filter "bif=baz")
The currently supported filters are:
- id (container's id)
- label (
label=<key>orlabel=<key>=<value>) - name (container's name)
- exited (int - the code of exited containers. Only useful with
--all) - status (created|restarting|running|paused|exited|dead)
- ancestor (
<image-name>[:<tag>],<image id>or<image@digest>) - filters containers that were created from the given image or a descendant. - before (container's id or name) - filters containers created before given id or name
- since (container's id or name) - filters containers created since given id or name
- isolation (default|process|hyperv) (Windows daemon only)
- volume (volume name or mount point) - filters containers that mount volumes.
- network (network id or name) - filters containers connected to the provided network
Label
The label filter matches containers based on the presence of a label alone or a label and a
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
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
Name
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
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
Exited
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
Killed containers
You can use a filter to locate containers that exited with status of 137
meaning a SIGKILL(9) killed them.
$ docker ps -a --filter 'exited=137'
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
b3e1c0ed5bfe ubuntu:latest "sleep 1000" 12 seconds ago Exited (137) 5 seconds ago grave_kowalevski
a2eb5558d669 redis:latest "/entrypoint.sh redi 2 hours ago Exited (137) 2 hours ago sharp_lalande
Any of these events result in a `137` status:
* the `init` process of the container is killed manually
* `docker kill` kills the container
* Docker daemon restarts which kills all running containers
#### 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:
bash $ docker ps --filter status=running
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
715ebfcee0 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic
d5c976d3c4 busybox "top" 23 minutes ago Up 23 minutes top
9b6247364a busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman
To filter for `paused` containers:
bash $ docker ps --filter status=paused
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
673394ef1d 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:
- image
- image:tag
- image:tag@digest
- 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:
bash $ docker ps --filter ancestor=ubuntu
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
919e1179bd ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
5d1e4a5407 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet
82a5982840 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose
bab2a34ba3 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath
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
919e1179bd ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
Match containers based on the `ubuntu` version `12.04.5` image:
bash $ docker ps --filter ancestor=ubuntu:12.04.5
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
82a5982840 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=d0e008c6cf
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
82a5982840 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:
bash $ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9c3527ed70 busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky
4aace50311 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton
6e63f6ff38 busybox "top" About a minute ago Up About a minute distracted_fermat
Filtering with `before` would give:
bash
$ docker ps -f before=9c3527ed70
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
4aace50311 busybox "top" About a minute ago Up About a minute focused_hamilton
6e63f6ff38 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:
bash
$ docker ps -f since=6e63f6ff38
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9c3527ed70 busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky
4aace50311 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:
bash
$ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}"
CONTAINER ID MOUNTS
9c3527ed70 remote-volume
$ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}"
CONTAINER ID MOUNTS
9c3527ed70 remote-volume
#### Network
The `network` filter shows only containers that are connected to a network with
a given name or id.
The following filter matches all containers that are connected to a network
with a name containing `net1`.
bash $ 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
9d4893ed80 ubuntu "top" 10 minutes ago Up 10 minutes test1
The network filter matches on both the network's name and id. The following
example shows all containers that are attached to the `net1` network, using
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
9d4893ed80 ubuntu "top" 10 minutes ago Up 10 minutes test1
## Formatting
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.
`.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.
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:
bash $ docker ps --format "{{.ID}}: {{.Command}}"
a87ecb4f32: /bin/sh -c #(nop) MA
01946d9d34: /bin/sh -c #(nop) MA
c1d3b01660: /bin/sh -c yum -y up
41d50ecd2f: /bin/sh -c #(nop) MA
To list all running containers with their labels in a table format you can use:
bash $ docker ps --format "table {{.ID}}\t{{.Labels}}"
CONTAINER ID LABELS
a87ecb4f32 com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd
01946d9d34
c1d3b01660 com.docker.swarm.node=debian,com.docker.swarm.cpu=6
41d50ecd2f com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd
```