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