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