| # images | |
| <!---MARKER_GEN_START--> | |
| List images | |
| ### Aliases | |
| `docker image ls`, `docker image list`, `docker images` | |
| ### Options | |
| | Name | Type | Default | Description | | |
| |:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | |
| | `-a`, `--all` | `bool` | | Show all images (default hides intermediate and dangling images) | | |
| | [`--digests`](#digests) | `bool` | | Show digests | | |
| | [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided | | |
| | [`--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 | | |
| | [`--no-trunc`](#no-trunc) | `bool` | | Don't truncate output | | |
| | `-q`, `--quiet` | `bool` | | Only show image IDs | | |
| | `--tree` | `bool` | | List multi-platform images as a tree (EXPERIMENTAL) | | |
| <!---MARKER_GEN_END--> | |
| ## Description | |
| The default `docker images` will show all top level | |
| images, their repository and tags, and their size. | |
| Docker images have intermediate layers that increase reusability, | |
| decrease disk usage, and speed up `docker build` by | |
| allowing each step to be cached. These intermediate layers are not shown | |
| by default. | |
| Untagged (dangling) images are also hidden by default. Use the `-a` (`--all`) | |
| flag to show intermediate layers and dangling images. | |
| The `SIZE` is the cumulative space taken up by the image and all | |
| its parent images. This is also the disk space used by the contents of the | |
| Tar file created when you `docker save` an image. | |
| An image will be listed more than once if it has multiple repository names | |
| or tags. This single image (identifiable by its matching `IMAGE ID`) | |
| uses up the `SIZE` listed only once. | |
| ## Examples | |
| ### List the most recently created images | |
| ```console | |
| $ docker images | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| <none> <none> 77af4d6b9913 19 hours ago 1.089 GB | |
| committ latest b6fa739cedf5 19 hours ago 1.089 GB | |
| <none> <none> 78a85c484f71 19 hours ago 1.089 GB | |
| docker latest 30557a29d5ab 20 hours ago 1.089 GB | |
| <none> <none> 5ed6274db6ce 24 hours ago 1.089 GB | |
| postgres 9 746b819f315e 4 days ago 213.4 MB | |
| postgres 9.3 746b819f315e 4 days ago 213.4 MB | |
| postgres 9.3.5 746b819f315e 4 days ago 213.4 MB | |
| postgres latest 746b819f315e 4 days ago 213.4 MB | |
| ``` | |
| ### List images by name and tag | |
| The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument | |
| that restricts the list to images that match the argument. If you specify | |
| `REPOSITORY`but no `TAG`, the `docker images` command lists all images in the | |
| given repository. | |
| For example, to list all images in the `java` repository, run the following command: | |
| ```console | |
| $ docker images java | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| java 8 308e519aac60 6 days ago 824.5 MB | |
| java 7 493d82594c15 3 months ago 656.3 MB | |
| java latest 2711b1d6f3aa 5 months ago 603.9 MB | |
| ``` | |
| The `[REPOSITORY[:TAG]]` value must be an exact match. This means that, for example, | |
| `docker images jav` does not match the image `java`. | |
| If both `REPOSITORY` and `TAG` are provided, only images matching that | |
| repository and tag are listed. To find all local images in the `java` | |
| repository with tag `8` you can use: | |
| ```console | |
| $ docker images java:8 | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| java 8 308e519aac60 6 days ago 824.5 MB | |
| ``` | |
| If nothing matches `REPOSITORY[:TAG]`, the list is empty. | |
| ```console | |
| $ docker images java:0 | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| ``` | |
| ### <a name="no-trunc"></a> List the full length image IDs (--no-trunc) | |
| ```console | |
| $ docker images --no-trunc | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| <none> <none> sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB | |
| committest latest sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB | |
| <none> <none> sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB | |
| docker latest sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB | |
| <none> <none> sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB | |
| <none> <none> sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB | |
| <none> <none> sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB | |
| tryout latest sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB | |
| <none> <none> sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB | |
| ``` | |
| ### <a name="digests"></a> List image digests (--digests) | |
| Images that use the v2 or later format have a content-addressable identifier | |
| called a `digest`. As long as the input used to generate the image is | |
| unchanged, the digest value is predictable. To list image digest values, use | |
| the `--digests` flag: | |
| ```console | |
| $ docker images --digests | |
| REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE | |
| localhost:5000/test/busybox <none> sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB | |
| ``` | |
| When pushing or pulling to a 2.0 registry, the `push` or `pull` command | |
| output includes the image digest. You can `pull` using a digest value. You can | |
| also reference by digest in `create`, `run`, and `rmi` commands, as well as the | |
| `FROM` image reference in a Dockerfile. | |
| ### <a name="filter"></a> Filtering (--filter) | |
| The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more | |
| than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`). | |
| The currently supported filters are: | |
| * dangling (boolean - true or false) | |
| * label (`label=<key>` or `label=<key>=<value>`) | |
| * before (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created before given id or references | |
| * since (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created since given id or references | |
| * reference (pattern of an image reference) - filter images whose reference matches the specified pattern | |
| #### Show untagged images (dangling) | |
| ```console | |
| $ docker images --filter "dangling=true" | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| <none> <none> 8abc22fbb042 4 weeks ago 0 B | |
| <none> <none> 48e5f45168b9 4 weeks ago 2.489 MB | |
| <none> <none> bf747efa0e2f 4 weeks ago 0 B | |
| <none> <none> 980fe10e5736 12 weeks ago 101.4 MB | |
| <none> <none> dea752e4e117 12 weeks ago 101.4 MB | |
| <none> <none> 511136ea3c5a 8 months ago 0 B | |
| ``` | |
| This will display untagged images that are the leaves of the images tree (not | |
| intermediary layers). These images occur when a new build of an image takes the | |
| `repo:tag` away from the image ID, leaving it as `<none>:<none>` or untagged. | |
| A warning will be issued if trying to remove an image when a container is presently | |
| using it. By having this flag it allows for batch cleanup. | |
| You can use this in conjunction with `docker rmi`: | |
| ```console | |
| $ docker rmi $(docker images -f "dangling=true" -q) | |
| 8abc22fbb042 | |
| 48e5f45168b9 | |
| bf747efa0e2f | |
| 980fe10e5736 | |
| dea752e4e117 | |
| 511136ea3c5a | |
| ``` | |
| Docker warns you if any containers exist that are using these untagged images. | |
| #### Show images with a given label | |
| The `label` filter matches images based on the presence of a `label` alone or a `label` and a | |
| value. | |
| The following filter matches images with the `com.example.version` label regardless of its value. | |
| ```console | |
| $ docker images --filter "label=com.example.version" | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB | |
| match-me-2 latest dea752e4e117 About a minute ago 188.3 MB | |
| ``` | |
| The following filter matches images with the `com.example.version` label with the `1.0` value. | |
| ```console | |
| $ docker images --filter "label=com.example.version=1.0" | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| match-me latest 511136ea3c5a About a minute ago 188.3 MB | |
| ``` | |
| In this example, with the `0.1` value, it returns an empty set because no matches were found. | |
| ```console | |
| $ docker images --filter "label=com.example.version=0.1" | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| ``` | |
| #### Filter images by time | |
| The `before` filter shows only images created before the image with | |
| a given ID or reference. For example, having these images: | |
| ```console | |
| $ docker images | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| image1 latest eeae25ada2aa 4 minutes ago 188.3 MB | |
| image2 latest dea752e4e117 9 minutes ago 188.3 MB | |
| image3 latest 511136ea3c5a 25 minutes ago 188.3 MB | |
| ``` | |
| Filtering with `before` would give: | |
| ```console | |
| $ docker images --filter "before=image1" | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| image2 latest dea752e4e117 9 minutes ago 188.3 MB | |
| image3 latest 511136ea3c5a 25 minutes ago 188.3 MB | |
| ``` | |
| Filtering with `since` would give: | |
| ```console | |
| $ docker images --filter "since=image3" | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| image1 latest eeae25ada2aa 4 minutes ago 188.3 MB | |
| image2 latest dea752e4e117 9 minutes ago 188.3 MB | |
| ``` | |
| #### Filter images by reference | |
| The `reference` filter shows only images whose reference matches | |
| the specified pattern. | |
| ```console | |
| $ docker images | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| busybox latest e02e811dd08f 5 weeks ago 1.09 MB | |
| busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB | |
| busybox musl 733eb3059dce 5 weeks ago 1.21 MB | |
| busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB | |
| ``` | |
| Filtering with `reference` would give: | |
| ```console | |
| $ docker images --filter=reference='busy*:*libc' | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB | |
| busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB | |
| ``` | |
| Filtering with multiple `reference` would give, either match A or B: | |
| ```console | |
| $ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc' | |
| REPOSITORY TAG IMAGE ID CREATED SIZE | |
| busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB | |
| busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB | |
| ``` | |
| ### <a name="format"></a> Format the output (--format) | |
| The formatting option (`--format`) will pretty print container output | |
| using a Go template. | |
| Valid placeholders for the Go template are listed below: | |
| | Placeholder | Description | | |
| |-----------------|------------------------------------------| | |
| | `.ID` | Image ID | | |
| | `.Repository` | Image repository | | |
| | `.Tag` | Image tag | | |
| | `.Digest` | Image digest | | |
| | `.CreatedSince` | Elapsed time since the image was created | | |
| | `.CreatedAt` | Time when the image was created | | |
| | `.Size` | Image disk size | | |
| When using the `--format` option, the `image` command will either | |
| output the data exactly as the template declares or, when using the | |
| `table` directive, will include column headers as well. | |
| The following example uses a template without headers and outputs the | |
| `ID` and `Repository` entries separated by a colon (`:`) for all images: | |
| ```console | |
| $ docker images --format "{{.ID}}: {{.Repository}}" | |
| 77af4d6b9913: <none> | |
| b6fa739cedf5: committ | |
| 78a85c484f71: <none> | |
| 30557a29d5ab: docker | |
| 5ed6274db6ce: <none> | |
| 746b819f315e: postgres | |
| 746b819f315e: postgres | |
| 746b819f315e: postgres | |
| 746b819f315e: postgres | |
| ``` | |
| To list all images with their repository and tag in a table format you | |
| can use: | |
| ```console | |
| $ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" | |
| IMAGE ID REPOSITORY TAG | |
| 77af4d6b9913 <none> <none> | |
| b6fa739cedf5 committ latest | |
| 78a85c484f71 <none> <none> | |
| 30557a29d5ab docker latest | |
| 5ed6274db6ce <none> <none> | |
| 746b819f315e postgres 9 | |
| 746b819f315e postgres 9.3 | |
| 746b819f315e postgres 9.3.5 | |
| 746b819f315e postgres latest | |
| ``` | |
| To list all images in JSON format, use the `json` directive: | |
| ```console | |
| $ docker images --format json | |
| {"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"} | |
| {"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"} | |
| ``` |