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