mirror of https://github.com/docker/docs.git
306 lines
22 KiB
YAML
306 lines
22 KiB
YAML
command: docker ps
|
|
short: List containers
|
|
long: List containers
|
|
usage: docker ps [OPTIONS]
|
|
pname: docker
|
|
plink: docker.yaml
|
|
options:
|
|
- option: all
|
|
shorthand: a
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Show all containers (default shows just running)
|
|
deprecated: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: filter
|
|
shorthand: f
|
|
value_type: filter
|
|
description: Filter output based on conditions provided
|
|
deprecated: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: format
|
|
value_type: string
|
|
description: Pretty-print containers using a Go template
|
|
deprecated: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: last
|
|
shorthand: "n"
|
|
value_type: int
|
|
default_value: "-1"
|
|
description: Show n last created containers (includes all states)
|
|
deprecated: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: latest
|
|
shorthand: l
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Show the latest created container (includes all states)
|
|
deprecated: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: no-trunc
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Don't truncate output
|
|
deprecated: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: quiet
|
|
shorthand: q
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Only display numeric IDs
|
|
deprecated: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: size
|
|
shorthand: s
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Display total file sizes
|
|
deprecated: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
examples: "### Prevent truncating output\n\nRunning `docker ps --no-trunc` showing
|
|
2 linked containers.\n\n```bash\n$ docker ps\n\nCONTAINER ID IMAGE COMMAND
|
|
\ CREATED STATUS PORTS NAMES\n4c01db0b339c
|
|
\ ubuntu:12.04 bash 17 seconds ago Up
|
|
16 seconds 3300-3310/tcp webapp\nd7886598dbe2 crosbymichael/redis:latest
|
|
\ /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db\n```\n\n###
|
|
Show both running and stopped containers\n\nThe `docker ps` command only shows running
|
|
containers by default. To see all\ncontainers, use the `-a` (or `--all`) flag:\n\n```bash\n$
|
|
docker ps -a\n```\n\n`docker ps` groups exposed ports into a single range if possible.
|
|
E.g., a\ncontainer that exposes TCP ports `100, 101, 102` displays `100-102/tcp`
|
|
in\nthe `PORTS` column.\n\n### Show disk usage by container\n\nThe `docker ps -s`
|
|
command displays two different on-disk-sizes for each container:\n\n```bash\n$ docker
|
|
ps -s\nCONTAINER ID IMAGE COMMAND CREATED STATUS
|
|
\ PORTS NAMES SIZE SIZE\ne90b8831a4b8
|
|
\ nginx \"/bin/bash -c 'mkdir \" 11 weeks ago Up 4 hours my_nginx
|
|
\ 35.58 kB (virtual 109.2 MB)\n00c6131c5e30 telegraf:1.5 \"/entrypoint.sh\"
|
|
\ 11 weeks ago Up 11 weeks my_telegraf 0 B (virtual 209.5 MB)\n```\n
|
|
\ * The \"size\" information shows the amount of data (on disk) that is used for
|
|
the _writable_ layer of each container\n * The \"virtual size\" is the total amount
|
|
of disk-space used for the read-only _image_ data used by the container and the
|
|
writable layer.\n \nFor more information, refer to the [container size on disk](https://docs.docker.com/storage/storagedriver/#container-size-on-disk)
|
|
section.\n\n\n### Filtering\n\nThe filtering flag (`-f` or `--filter`) format is
|
|
a `key=value` pair. If there is more\nthan one filter, then pass multiple flags
|
|
(e.g. `--filter \"foo=bar\" --filter \"bif=baz\"`)\n\nThe currently supported filters
|
|
are:\n\n| Filter | Description |\n|:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------|\n|
|
|
`id` | Container's ID |\n|
|
|
`name` | Container's name |\n|
|
|
`label` | An arbitrary string representing either a key or a key-value
|
|
pair. Expressed as `<key>` or `<key>=<value>` |\n| `exited`
|
|
\ | An integer representing the container's exit code. Only useful with
|
|
`--all`. |\n| `status` |
|
|
One of `created`, `restarting`, `running`, `removing`, `paused`, `exited`, or `dead`
|
|
\ |\n| `ancestor` | Filters
|
|
containers which share a given image as an ancestor. Expressed as `<image-name>[:<tag>]`,
|
|
\ `<image id>`, or `<image@digest>` |\n| `before` or `since` | Filters containers
|
|
created before or after a given container ID or name |\n|
|
|
`volume` | Filters running containers which have mounted a given volume
|
|
or bind mount. |\n| `network`
|
|
\ | Filters running containers connected to a given network. |\n|
|
|
`publish` or `expose` | Filters containers which publish or expose a given port.
|
|
Expressed as `<port>[/<proto>]` or `<startport-endport>/[<proto>]` |\n|
|
|
`health` | Filters containers based on their healthcheck status. One
|
|
of `starting`, `healthy`, `unhealthy` or `none`. |\n|
|
|
`isolation` | Windows daemon only. One of `default`, `process`, or `hyperv`.
|
|
\ |\n| `is-task`
|
|
\ | Filters containers that are a \"task\" for a service. Boolean option
|
|
(`true` or `false`) |\n\n\n#### label\n\nThe
|
|
`label` filter matches containers based on the presence of a `label` alone or a
|
|
`label` and a\nvalue.\n\nThe following filter matches containers with the `color`
|
|
label regardless of its value.\n\n```bash\n$ docker ps --filter \"label=color\"\n\nCONTAINER
|
|
ID IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\n673394ef1d4c busybox \"top\" 47
|
|
seconds ago Up 45 seconds nostalgic_shockley\nd85756f57265
|
|
\ busybox \"top\" 52 seconds ago Up 51 seconds
|
|
\ high_albattani\n```\n\nThe following filter matches containers
|
|
with the `color` label with the `blue` value.\n\n```bash\n$ docker ps --filter \"label=color=blue\"\n\nCONTAINER
|
|
ID IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\nd85756f57265 busybox \"top\" About
|
|
a minute ago Up About a minute high_albattani\n```\n\n####
|
|
name\n\nThe `name` filter matches on all or part of a container's name.\n\nThe following
|
|
filter matches all containers with a name containing the `nostalgic_stallman` string.\n\n```bash\n$
|
|
docker ps --filter \"name=nostalgic_stallman\"\n\nCONTAINER ID IMAGE COMMAND
|
|
\ CREATED STATUS PORTS NAMES\n9b6247364a03
|
|
\ busybox \"top\" 2 minutes ago Up 2 minutes
|
|
\ nostalgic_stallman\n```\n\nYou can also filter for a
|
|
substring in a name as this shows:\n\n```bash\n$ docker ps --filter \"name=nostalgic\"\n\nCONTAINER
|
|
ID IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\n715ebfcee040 busybox \"top\" 3
|
|
seconds ago Up 1 second i_am_nostalgic\n9b6247364a03
|
|
\ busybox \"top\" 7 minutes ago Up 7 minutes
|
|
\ nostalgic_stallman\n673394ef1d4c busybox \"top\"
|
|
\ 38 minutes ago Up 38 minutes nostalgic_shockley\n```\n\n####
|
|
exited\n\nThe `exited` filter matches containers by exist status code. For example,
|
|
to\nfilter for containers that have exited successfully:\n\n```bash\n$ docker ps
|
|
-a --filter 'exited=0'\n\nCONTAINER ID IMAGE COMMAND CREATED
|
|
\ STATUS PORTS NAMES\nea09c3c82f6e
|
|
\ registry:latest /srv/run.sh 2 weeks ago Exited (0)
|
|
2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey\n106ea823fe4e fedora:latest
|
|
\ /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani\n48ee228c9464
|
|
\ fedora:20 bash 2 weeks ago Exited (0)
|
|
2 weeks ago tender_torvalds\n```\n\n#### Filter by
|
|
exit signal\n\nYou can use a filter to locate containers that exited with status
|
|
of `137`\nmeaning a `SIGKILL(9)` killed them.\n\n```none\n$ docker ps -a --filter
|
|
'exited=137'\n\nCONTAINER ID IMAGE COMMAND CREATED
|
|
\ STATUS PORTS NAMES\nb3e1c0ed5bfe
|
|
\ ubuntu:latest \"sleep 1000\" 12 seconds ago Exited
|
|
(137) 5 seconds ago grave_kowalevski\na2eb5558d669 redis:latest
|
|
\ \"/entrypoint.sh redi 2 hours ago Exited (137) 2 hours ago sharp_lalande\n```\n\nAny
|
|
of these events result in a `137` status:\n\n* the `init` process of the container
|
|
is killed manually\n* `docker kill` kills the container\n* Docker daemon restarts
|
|
which kills all running containers\n\n#### status\n\nThe `status` filter matches
|
|
containers by status. You can filter using\n`created`, `restarting`, `running`,
|
|
`removing`, `paused`, `exited` and `dead`. For example,\nto filter for `running`
|
|
containers:\n\n```bash\n$ docker ps --filter status=running\n\nCONTAINER ID IMAGE
|
|
\ COMMAND CREATED STATUS PORTS
|
|
\ NAMES\n715ebfcee040 busybox \"top\" 16
|
|
minutes ago Up 16 minutes i_am_nostalgic\nd5c976d3c462
|
|
\ busybox \"top\" 23 minutes ago Up 23 minutes
|
|
\ top\n9b6247364a03 busybox \"top\"
|
|
\ 24 minutes ago Up 24 minutes nostalgic_stallman\n```\n\nTo
|
|
filter for `paused` containers:\n\n```bash\n$ docker ps --filter status=paused\n\nCONTAINER
|
|
ID IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\n673394ef1d4c busybox \"top\" About
|
|
an hour ago Up About an hour (Paused) nostalgic_shockley\n```\n\n####
|
|
ancestor\n\nThe `ancestor` filter matches containers based on its image or a descendant
|
|
of\nit. The filter supports the following image representation:\n\n- `image`\n-
|
|
`image:tag`\n- `image:tag@digest`\n- `short-id`\n- `full-id`\n\nIf you don't specify
|
|
a `tag`, the `latest` tag is used. For example, to filter\nfor containers that use
|
|
the latest `ubuntu` image:\n\n```bash\n$ docker ps --filter ancestor=ubuntu\n\nCONTAINER
|
|
ID IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\n919e1179bdb8 ubuntu-c1 \"top\" About
|
|
a minute ago Up About a minute admiring_lovelace\n5d1e4a540723
|
|
\ ubuntu-c2 \"top\" About a minute ago Up About
|
|
a minute admiring_sammet\n82a598284012 ubuntu \"top\"
|
|
\ 3 minutes ago Up 3 minutes sleepy_bose\nbab2a34ba363
|
|
\ ubuntu \"top\" 3 minutes ago Up 3 minutes
|
|
\ focused_yonath\n```\n\nMatch containers based on the
|
|
`ubuntu-c1` image which, in this case, is a child\nof `ubuntu`:\n\n```bash\n$ docker
|
|
ps --filter ancestor=ubuntu-c1\n\nCONTAINER ID IMAGE COMMAND
|
|
\ CREATED STATUS PORTS NAMES\n919e1179bdb8
|
|
\ ubuntu-c1 \"top\" About a minute ago Up About
|
|
a minute admiring_lovelace\n```\n\nMatch containers based
|
|
on the `ubuntu` version `12.04.5` image:\n\n```bash\n$ docker ps --filter ancestor=ubuntu:12.04.5\n\nCONTAINER
|
|
ID IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\n82a598284012 ubuntu:12.04.5 \"top\" 3
|
|
minutes ago Up 3 minutes sleepy_bose\n```\n\nThe
|
|
following matches containers based on the layer `d0e008c6cf02` or an image\nthat
|
|
have this layer in its layer stack.\n\n```bash\n$ docker ps --filter ancestor=d0e008c6cf02\n\nCONTAINER
|
|
ID IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\n82a598284012 ubuntu:12.04.5 \"top\" 3
|
|
minutes ago Up 3 minutes sleepy_bose\n```\n\n####
|
|
Create time\n\n##### before\n\nThe `before` filter shows only containers created
|
|
before the container with\ngiven id or name. For example, having these containers
|
|
created:\n\n```bash\n$ docker ps\n\nCONTAINER ID IMAGE COMMAND CREATED
|
|
\ STATUS PORTS NAMES\n9c3527ed70ce busybox
|
|
\ \"top\" 14 seconds ago Up 15 seconds desperate_dubinsky\n4aace5031105
|
|
\ busybox \"top\" 48 seconds ago Up 49 seconds focused_hamilton\n6e63f6ff38b0
|
|
\ busybox \"top\" About a minute ago Up About a minute distracted_fermat\n```\n\nFiltering
|
|
with `before` would give:\n\n```bash\n$ docker ps -f before=9c3527ed70ce\n\nCONTAINER
|
|
ID IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\n4aace5031105 busybox \"top\" About a minute
|
|
ago Up About a minute focused_hamilton\n6e63f6ff38b0 busybox
|
|
\ \"top\" About a minute ago Up About a minute distracted_fermat\n```\n\n#####
|
|
since\n\nThe `since` filter shows only containers created since the container with
|
|
given\nid or name. For example, with the same containers as in `before` filter:\n\n```bash\n$
|
|
docker ps -f since=6e63f6ff38b0\n\nCONTAINER ID IMAGE COMMAND CREATED
|
|
\ STATUS PORTS NAMES\n9c3527ed70ce busybox
|
|
\ \"top\" 10 minutes ago Up 10 minutes desperate_dubinsky\n4aace5031105
|
|
\ busybox \"top\" 10 minutes ago Up 10 minutes focused_hamilton\n```\n\n####
|
|
volume\n\nThe `volume` filter shows only containers that mount a specific volume
|
|
or have\na volume mounted in a specific path:\n\n```bash\n$ docker ps --filter volume=remote-volume
|
|
--format \"table {{.ID}}\\t{{.Mounts}}\"\nCONTAINER ID MOUNTS\n9c3527ed70ce
|
|
\ remote-volume\n\n$ docker ps --filter volume=/data --format \"table {{.ID}}\\t{{.Mounts}}\"\nCONTAINER
|
|
ID MOUNTS\n9c3527ed70ce remote-volume\n```\n\n#### network\n\nThe
|
|
`network` filter shows only containers that are connected to a network with\na given
|
|
name or id.\n\nThe following filter matches all containers that are connected to
|
|
a network\nwith a name containing `net1`.\n\n```bash\n$ docker run -d --net=net1
|
|
--name=test1 ubuntu top\n$ docker run -d --net=net2 --name=test2 ubuntu top\n\n$
|
|
docker ps --filter network=net1\n\nCONTAINER ID IMAGE COMMAND CREATED
|
|
\ STATUS PORTS NAMES\n9d4893ed80fe ubuntu
|
|
\ \"top\" 10 minutes ago Up 10 minutes test1\n```\n\nThe
|
|
network filter matches on both the network's name and id. The following\nexample
|
|
shows all containers that are attached to the `net1` network, using\nthe network
|
|
id as a filter;\n\n```bash\n$ docker network inspect --format \"{{.ID}}\" net1\n\n8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5\n\n$
|
|
docker ps --filter network=8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5\n\nCONTAINER
|
|
ID IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\n9d4893ed80fe ubuntu \"top\" 10 minutes
|
|
ago Up 10 minutes test1\n```\n\n#### publish and
|
|
expose\n\nThe `publish` and `expose` filters show only containers that have published
|
|
or exposed port with a given port\nnumber, port range, and/or protocol. The default
|
|
protocol is `tcp` when not specified.\n\nThe following filter matches all containers
|
|
that have published port of 80:\n\n```bash\n$ docker run -d --publish=80 busybox
|
|
top\n$ docker run -d --expose=8080 busybox top\n\n$ docker ps -a\n\nCONTAINER ID
|
|
\ IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\n9833437217a5 busybox \"top\" 5
|
|
seconds ago Up 4 seconds 8080/tcp dreamy_mccarthy\nfc7e477723b7
|
|
\ busybox \"top\" 50 seconds ago Up 50 seconds
|
|
\ 0.0.0.0:32768->80/tcp admiring_roentgen\n\n$ docker ps --filter publish=80\n\nCONTAINER
|
|
ID IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\nfc7e477723b7 busybox \"top\" About
|
|
a minute ago Up About a minute 0.0.0.0:32768->80/tcp admiring_roentgen\n```\n\nThe
|
|
following filter matches all containers that have exposed TCP port in the range
|
|
of `8000-8080`:\n```bash\n$ docker ps --filter expose=8000-8080/tcp\n\nCONTAINER
|
|
ID IMAGE COMMAND CREATED STATUS PORTS
|
|
\ NAMES\n9833437217a5 busybox \"top\" 21
|
|
seconds ago Up 19 seconds 8080/tcp dreamy_mccarthy\n```\n\nThe
|
|
following filter matches all containers that have exposed UDP port `80`:\n```bash\n$
|
|
docker ps --filter publish=80/udp\n\nCONTAINER ID IMAGE COMMAND
|
|
\ CREATED STATUS PORTS NAMES\n```\n\n###
|
|
Formatting\n\nThe formatting option (`--format`) pretty-prints container output
|
|
using a Go\ntemplate.\n\nValid placeholders for the Go template are listed below:\n\n|
|
|
Placeholder | Description |\n|:--------------|:------------------------------------------------------------------------------------------------|\n|
|
|
`.ID` | Container ID |\n|
|
|
`.Image` | Image ID |\n|
|
|
`.Command` | Quoted command |\n|
|
|
`.CreatedAt` | Time when the container was created. |\n|
|
|
`.RunningFor` | Elapsed time since the container was started. |\n|
|
|
`.Ports` | Exposed ports. |\n|
|
|
`.Status` | Container status. |\n|
|
|
`.Size` | Container disk size. |\n|
|
|
`.Names` | Container names. |\n|
|
|
`.Labels` | All labels assigned to the container. |\n|
|
|
`.Label` | Value of a specific label for this container. For example `'{{.Label
|
|
\"com.docker.swarm.cpu\"}}'` |\n| `.Mounts` | Names of the volumes mounted in
|
|
this container. |\n| `.Networks`
|
|
\ | Names of the networks attached to this container. |\n\nWhen
|
|
using the `--format` option, the `ps` command will either output the data\nexactly
|
|
as the template declares or, when using the `table` directive, includes\ncolumn
|
|
headers as well.\n\nThe following example uses a template without headers and outputs
|
|
the `ID` and\n`Command` entries separated by a colon for all running containers:\n\n```bash\n$
|
|
docker ps --format \"{{.ID}}: {{.Command}}\"\n\na87ecb4f327c: /bin/sh -c #(nop)
|
|
MA\n01946d9d34d8: /bin/sh -c #(nop) MA\nc1d3b0166030: /bin/sh -c yum -y up\n41d50ecd2f57:
|
|
/bin/sh -c #(nop) MA\n```\n\nTo list all running containers with their labels in
|
|
a table format you can use:\n\n```bash\n$ docker ps --format \"table {{.ID}}\\t{{.Labels}}\"\n\nCONTAINER
|
|
ID LABELS\na87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd\n01946d9d34d8\nc1d3b0166030
|
|
\ com.docker.swarm.node=debian,com.docker.swarm.cpu=6\n41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd\n```"
|
|
deprecated: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
|