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