1# images
2
3<!---MARKER_GEN_START-->
4List images
5
6### Aliases
7
8`docker image ls`, `docker image list`, `docker images`
9
10### Options
11
12| Name | Type | Default | Description |
13|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
14| `-a`, `--all` | | | Show all images (default hides intermediate images) |
15| [`--digests`](#digests) | | | Show digests |
16| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided |
17| [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
18| [`--no-trunc`](#no-trunc) | | | Don't truncate output |
19| `-q`, `--quiet` | | | Only show image IDs |
20
21
22<!---MARKER_GEN_END-->
23
24## Description
25
26The default `docker images` will show all top level
27images, their repository and tags, and their size.
28
29Docker images have intermediate layers that increase reusability,
30decrease disk usage, and speed up `docker build` by
31allowing each step to be cached. These intermediate layers are not shown
32by default.
33
34The `SIZE` is the cumulative space taken up by the image and all
35its parent images. This is also the disk space used by the contents of the
36Tar file created when you `docker save` an image.
37
38An image will be listed more than once if it has multiple repository names
39or tags. This single image (identifiable by its matching `IMAGE ID`)
40uses up the `SIZE` listed only once.
41
42## Examples
43
44### List the most recently created images
45
46```console
47$ docker images
48
49REPOSITORY TAG IMAGE ID CREATED SIZE
50<none> <none> 77af4d6b9913 19 hours ago 1.089 GB
51committ latest b6fa739cedf5 19 hours ago 1.089 GB
52<none> <none> 78a85c484f71 19 hours ago 1.089 GB
53docker latest 30557a29d5ab 20 hours ago 1.089 GB
54<none> <none> 5ed6274db6ce 24 hours ago 1.089 GB
55postgres 9 746b819f315e 4 days ago 213.4 MB
56postgres 9.3 746b819f315e 4 days ago 213.4 MB
57postgres 9.3.5 746b819f315e 4 days ago 213.4 MB
58postgres latest 746b819f315e 4 days ago 213.4 MB
59```
60
61### List images by name and tag
62
63The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument
64that restricts the list to images that match the argument. If you specify
65`REPOSITORY`but no `TAG`, the `docker images` command lists all images in the
66given repository.
67
68For example, to list all images in the `java` repository, run the following command:
69
70```console
71$ docker images java
72
73REPOSITORY TAG IMAGE ID CREATED SIZE
74java 8 308e519aac60 6 days ago 824.5 MB
75java 7 493d82594c15 3 months ago 656.3 MB
76java latest 2711b1d6f3aa 5 months ago 603.9 MB
77```
78
79The `[REPOSITORY[:TAG]]` value must be an exact match. This means that, for example,
80`docker images jav` does not match the image `java`.
81
82If both `REPOSITORY` and `TAG` are provided, only images matching that
83repository and tag are listed. To find all local images in the `java`
84repository with tag `8` you can use:
85
86```console
87$ docker images java:8
88
89REPOSITORY TAG IMAGE ID CREATED SIZE
90java 8 308e519aac60 6 days ago 824.5 MB
91```
92
93If nothing matches `REPOSITORY[:TAG]`, the list is empty.
94
95```console
96$ docker images java:0
97
98REPOSITORY TAG IMAGE ID CREATED SIZE
99```
100
101### <a name="no-trunc"></a> List the full length image IDs (--no-trunc)
102
103```console
104$ docker images --no-trunc
105
106REPOSITORY TAG IMAGE ID CREATED SIZE
107<none> <none> sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB
108committest latest sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB
109<none> <none> sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB
110docker latest sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB
111<none> <none> sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB
112<none> <none> sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB
113<none> <none> sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB
114tryout latest sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB
115<none> <none> sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB
116```
117
118### <a name="digests"></a> List image digests (--digests)
119
120Images that use the v2 or later format have a content-addressable identifier
121called a `digest`. As long as the input used to generate the image is
122unchanged, the digest value is predictable. To list image digest values, use
123the `--digests` flag:
124
125```console
126$ docker images --digests
127REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE
128localhost:5000/test/busybox <none> sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB
129```
130
131When pushing or pulling to a 2.0 registry, the `push` or `pull` command
132output includes the image digest. You can `pull` using a digest value. You can
133also reference by digest in `create`, `run`, and `rmi` commands, as well as the
134`FROM` image reference in a Dockerfile.
135
136### <a name="filter"></a> Filtering (--filter)
137
138The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
139than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).
140
141The currently supported filters are:
142
143* dangling (boolean - true or false)
144* label (`label=<key>` or `label=<key>=<value>`)
145* before (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created before given id or references
146* since (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created since given id or references
147* reference (pattern of an image reference) - filter images whose reference matches the specified pattern
148
149#### Show untagged images (dangling)
150
151```console
152$ docker images --filter "dangling=true"
153
154REPOSITORY TAG IMAGE ID CREATED SIZE
155<none> <none> 8abc22fbb042 4 weeks ago 0 B
156<none> <none> 48e5f45168b9 4 weeks ago 2.489 MB
157<none> <none> bf747efa0e2f 4 weeks ago 0 B
158<none> <none> 980fe10e5736 12 weeks ago 101.4 MB
159<none> <none> dea752e4e117 12 weeks ago 101.4 MB
160<none> <none> 511136ea3c5a 8 months ago 0 B
161```
162
163This will display untagged images that are the leaves of the images tree (not
164intermediary layers). These images occur when a new build of an image takes the
165`repo:tag` away from the image ID, leaving it as `<none>:<none>` or untagged.
166A warning will be issued if trying to remove an image when a container is presently
167using it. By having this flag it allows for batch cleanup.
168
169You can use this in conjunction with `docker rmi`:
170
171```console
172$ docker rmi $(docker images -f "dangling=true" -q)
173
1748abc22fbb042
17548e5f45168b9
176bf747efa0e2f
177980fe10e5736
178dea752e4e117
179511136ea3c5a
180```
181
182Docker warns you if any containers exist that are using these untagged images.
183
184
185#### Show images with a given label
186
187The `label` filter matches images based on the presence of a `label` alone or a `label` and a
188value.
189
190The following filter matches images with the `com.example.version` label regardless of its value.
191
192```console
193$ docker images --filter "label=com.example.version"
194
195REPOSITORY TAG IMAGE ID CREATED SIZE
196match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB
197match-me-2 latest dea752e4e117 About a minute ago 188.3 MB
198```
199
200The following filter matches images with the `com.example.version` label with the `1.0` value.
201
202```console
203$ docker images --filter "label=com.example.version=1.0"
204
205REPOSITORY TAG IMAGE ID CREATED SIZE
206match-me latest 511136ea3c5a About a minute ago 188.3 MB
207```
208
209In this example, with the `0.1` value, it returns an empty set because no matches were found.
210
211```console
212$ docker images --filter "label=com.example.version=0.1"
213REPOSITORY TAG IMAGE ID CREATED SIZE
214```
215
216#### Filter images by time
217
218The `before` filter shows only images created before the image with
219a given ID or reference. For example, having these images:
220
221```console
222$ docker images
223
224REPOSITORY TAG IMAGE ID CREATED SIZE
225image1 latest eeae25ada2aa 4 minutes ago 188.3 MB
226image2 latest dea752e4e117 9 minutes ago 188.3 MB
227image3 latest 511136ea3c5a 25 minutes ago 188.3 MB
228```
229
230Filtering with `before` would give:
231
232```console
233$ docker images --filter "before=image1"
234
235REPOSITORY TAG IMAGE ID CREATED SIZE
236image2 latest dea752e4e117 9 minutes ago 188.3 MB
237image3 latest 511136ea3c5a 25 minutes ago 188.3 MB
238```
239
240Filtering with `since` would give:
241
242```console
243$ docker images --filter "since=image3"
244REPOSITORY TAG IMAGE ID CREATED SIZE
245image1 latest eeae25ada2aa 4 minutes ago 188.3 MB
246image2 latest dea752e4e117 9 minutes ago 188.3 MB
247```
248
249#### Filter images by reference
250
251The `reference` filter shows only images whose reference matches
252the specified pattern.
253
254```console
255$ docker images
256
257REPOSITORY TAG IMAGE ID CREATED SIZE
258busybox latest e02e811dd08f 5 weeks ago 1.09 MB
259busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
260busybox musl 733eb3059dce 5 weeks ago 1.21 MB
261busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
262```
263
264Filtering with `reference` would give:
265
266```console
267$ docker images --filter=reference='busy*:*libc'
268
269REPOSITORY TAG IMAGE ID CREATED SIZE
270busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
271busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
272```
273
274Filtering with multiple `reference` would give, either match A or B:
275
276```console
277$ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc'
278
279REPOSITORY TAG IMAGE ID CREATED SIZE
280busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
281busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
282```
283
284### <a name="format"></a> Format the output (--format)
285
286The formatting option (`--format`) will pretty print container output
287using a Go template.
288
289Valid placeholders for the Go template are listed below:
290
291| Placeholder | Description |
292|-----------------|------------------------------------------|
293| `.ID` | Image ID |
294| `.Repository` | Image repository |
295| `.Tag` | Image tag |
296| `.Digest` | Image digest |
297| `.CreatedSince` | Elapsed time since the image was created |
298| `.CreatedAt` | Time when the image was created |
299| `.Size` | Image disk size |
300
301When using the `--format` option, the `image` command will either
302output the data exactly as the template declares or, when using the
303`table` directive, will include column headers as well.
304
305The following example uses a template without headers and outputs the
306`ID` and `Repository` entries separated by a colon (`:`) for all images:
307
308```console
309$ docker images --format "{{.ID}}: {{.Repository}}"
310
31177af4d6b9913: <none>
312b6fa739cedf5: committ
31378a85c484f71: <none>
31430557a29d5ab: docker
3155ed6274db6ce: <none>
316746b819f315e: postgres
317746b819f315e: postgres
318746b819f315e: postgres
319746b819f315e: postgres
320```
321
322To list all images with their repository and tag in a table format you
323can use:
324
325```console
326$ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
327
328IMAGE ID REPOSITORY TAG
32977af4d6b9913 <none> <none>
330b6fa739cedf5 committ latest
33178a85c484f71 <none> <none>
33230557a29d5ab docker latest
3335ed6274db6ce <none> <none>
334746b819f315e postgres 9
335746b819f315e postgres 9.3
336746b819f315e postgres 9.3.5
337746b819f315e postgres latest
338```
339
340To list all images in JSON format, use the `json` directive:
341
342```console
343$ docker images --format json
344{"Containers":"N/A","CreatedAt":"2021-03-04 03:24:42 +0100 CET","CreatedSince":"5 days ago","Digest":"\u003cnone\u003e","ID":"4dd97cefde62","Repository":"ubuntu","SharedSize":"N/A","Size":"72.9MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"72.9MB"}
345{"Containers":"N/A","CreatedAt":"2021-02-17 22:19:54 +0100 CET","CreatedSince":"2 weeks ago","Digest":"\u003cnone\u003e","ID":"28f6e2705743","Repository":"alpine","SharedSize":"N/A","Size":"5.61MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"5.613MB"}
346```
View as plain text