1DOCKER(1)                        FEBRUARY 2015                       DOCKER(1)
2
3
4

NAME

6       docker-ps - List containers
7
8
9

SYNOPSIS

11       docker ps [-a|--all] [-f|--filter[=[]]] [--format="TEMPLATE"] [--help]
12       [-l|--latest] [-n[=-1]] [--no-trunc] [-q|--quiet] [-s|--size]
13
14
15

DESCRIPTION

17       List the containers in the local repository. By default this shows only
18       the running containers.
19
20
21

OPTIONS

23       -a, --all=true|false
24          Show all containers. Only running containers are shown by default.
25       The default is false.
26
27
28       -f, --filter=[]
29          Filter output based on these conditions:
30          - exited=<int> an exit code of <int>
31          - label=<key> or label=<key>=<value>
32          - status=(created|restarting|running|paused|exited|dead)
33          - name=<string> a container's name
34          - id=<ID> a container's ID
35          - is-task=(true|false) - containers that are a task (part of a
36       service managed by swarm)
37          - before=(<container-name>|<container-id>)
38          - since=(<container-name>|<container-id>)
39          - ancestor=(<image-name>[:tag]|<image-id>| ⟨image@digest⟩) -
40       containers created from an image or a descendant.
41          - volume=(<volume-name>|<mount-point-destination>)
42          - network=(<network-name>|<network-id>) - containers connected to
43       the provided network
44          - health=(starting|healthy|unhealthy|none) - filters containers
45       based on healthcheck status
46
47
48       --format="TEMPLATE"
49          Pretty-print containers using a Go template.
50          Valid placeholders:
51             .ID - Container ID
52             .Image - Image ID
53             .Command - Quoted command
54             .CreatedAt - Time when the container was created.
55             .RunningFor - Elapsed time since the container was started.
56             .Ports - Exposed ports.
57             .Status - Container status.
58             .Size - Container disk size.
59             .Names - Container names.
60             .Labels - All labels assigned to the container.
61             .Label - Value of a specific label for this container. For
62       example {{.Label "com.docker.swarm.cpu"}}
63             .Mounts - Names of the volumes mounted in this container.
64
65
66       --help
67         Print usage statement
68
69
70       -l, --latest=true|false
71          Show only the latest created container (includes all states). The
72       default is false.
73
74
75       -n=-1
76          Show n last created containers (includes all states).
77
78
79       --no-trunc=true|false
80          Don't truncate output. The default is false.
81
82
83       -q, --quiet=true|false
84          Only display numeric IDs. The default is false.
85
86
87       -s, --size=true|false
88          Display total file sizes. The default is false.
89
90
91

EXAMPLES

Display all containers, including non-running

94              # docker ps -a
95              CONTAINER ID        IMAGE                 COMMAND                CREATED             STATUS      PORTS    NAMES
96              a87ecb4f327c        fedora:20             /bin/sh -c #(nop) MA   20 minutes ago      Exit 0               desperate_brattain
97              01946d9d34d8        vpavlin/rhel7:latest  /bin/sh -c #(nop) MA   33 minutes ago      Exit 0               thirsty_bell
98              c1d3b0166030        acffc0358b9e          /bin/sh -c yum -y up   2 weeks ago         Exit 1               determined_torvalds
99              41d50ecd2f57        fedora:20             /bin/sh -c #(nop) MA   2 weeks ago         Exit 0               drunk_pike
100
101
102
103

Display only IDs of all containers, including non-running

105              # docker ps -a -q
106              a87ecb4f327c
107              01946d9d34d8
108              c1d3b0166030
109              41d50ecd2f57
110
111
112
113

Display only IDs of all containers that have the name determined_torvalds

115              # docker ps -a -q --filter=name=determined_torvalds
116              c1d3b0166030
117
118
119
120

Display containers with their commands

122              # docker ps --format "{{.ID}}: {{.Command}}"
123              a87ecb4f327c: /bin/sh -c #(nop) MA
124              01946d9d34d8: /bin/sh -c #(nop) MA
125              c1d3b0166030: /bin/sh -c yum -y up
126              41d50ecd2f57: /bin/sh -c #(nop) MA
127
128
129
130

Display containers with their labels in a table

132              # docker ps --format "table {{.ID}}\t{{.Labels}}"
133              CONTAINER ID        LABELS
134              a87ecb4f327c        com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd
135              01946d9d34d8
136              c1d3b0166030        com.docker.swarm.node=debian,com.docker.swarm.cpu=6
137              41d50ecd2f57        com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd
138
139
140
141

Display containers with their node label in a table

143              # docker ps --format 'table {{.ID}}\t{{(.Label "com.docker.swarm.node")}}'
144              CONTAINER ID        NODE
145              a87ecb4f327c        ubuntu
146              01946d9d34d8
147              c1d3b0166030        debian
148              41d50ecd2f57        fedora
149
150
151
152

Display containers with remote-volume mounted

154              $ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}"
155              CONTAINER ID        MOUNTS
156              9c3527ed70ce        remote-volume
157
158
159
160

Display containers with a volume mounted in /data

162              $ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}"
163              CONTAINER ID        MOUNTS
164              9c3527ed70ce        remote-volume
165
166
167
168

HISTORY

170       April 2014, Originally compiled by William Henry (whenry at redhat dot
171       com) based on docker.com source material and internal work.  June 2014,
172       updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩ August 2014,
173       updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩ November 2014,
174       updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩ February 2015,
175       updated by André Martins ⟨martins@noironetworks.com⟩ October 2016,
176       updated by Josh Horwitz ⟨horwitzja@gmail.com⟩
177
178
179
180Docker Community              Docker User Manuals                    DOCKER(1)
Impressum