# docker image ls

## 描述

* 列出本地的 Docker 镜像 (images)。
* 默认只显示 “顶层 (top-level)” 镜像 (不显示中间层镜像)。
* “SIZE” 列显示的是该镜像及其所有父镜像所占用的累积空间。
* 如果一个镜像有多个标签 (tag) 或多个仓库 (repository 名称)，那么它可能会在列表中出现多次 (但其 ID 是相同的)。

## 用法

```
docker image ls [OPTIONS] [REPOSITORY[:TAG]]
```

* `REPOSITORY[:TAG]` 可以指定仓库和标签，以过滤你只关心的镜像。
* 别名 (Aliases)：`docker image list` 或 `docker images` 都等价于 `docker image ls`。

## 选项

| 选项             | 含义                                                                         |
| -------------- | -------------------------------------------------------------------------- |
| `-a, --all`    | 显示所有镜像，包括中间层镜像 (默认不显示中间层)。                                                 |
| `--digests`    | 显示镜像的 digest (内容可寻址标识符)。                                                   |
| `-f, --filter` | 根据指定条件过滤镜像。支持多种过滤 key (如 `dangling`、`label`、`before`、`since`、`reference`)。 |
| `--format`     | 使用 Go 模板自定义输出格式。可选格式包括 `table`、`json` 或自定义 TEMPLATE。 支持的占位符 (Go 模板变量)：     |

* `.ID`：镜像 ID
* `.Repository`：仓库名
* `.Tag`：标签 (Tag)
* `.Digest`：镜像摘要 (digest)
* `.CreatedSince`：镜像创建以来的时间 (多久之前)
* `.CreatedAt`：创建时间
* `.Size`：镜像大小 (磁盘占用) | `--no-trunc` | 不截断输出 (默认情况下部分字段可能被截断显示)。 | | `-q, --quiet` | 只输出镜像 ID，不显示表格或其他详细信息。 | | `--tree` | 实验性选项 (API 1.47+): 将多平台 (multi-platform) 镜像以树形结构显示 (CLI 实验功能)。 |

## 示例 (Examples)

* 列出所有镜像 (默认)：

  ```bash
  docker image ls
  ```

  这将显示镜像的仓库名、标签、镜像 ID、创建时间、大小等。
* 显示某个仓库下某标签的镜像：

  ```bash
  docker image ls ubuntu:20.04
  ```

  只列出 `ubuntu:20.04` 这个具体镜像 (如果存在)。
* 使用 `--no-trunc` 显示完整 ID：

  ```bash
  docker image ls --no-trunc
  ```

  这可以看到完整的镜像 ID (SHA) 而不是被省略。
* 只显示镜像 ID：

  ```bash
  docker image ls -q
  ```

  适合脚本里用，比如配合 `docker rmi` 批量删除镜像。
* 显示 digest：

  ```bash
  docker image ls --digests
  ```

  可以看到每个镜像的 digest (如果有的话)。
* 用过滤器 (filter)：
  * 显示未打标签 (“悬空”镜像)：

    ```bash
    docker image ls --filter "dangling=true"
    ```

    这样可以列出没有 tag 的镜像 (通常是中间层或未引用的镜像)。
  * 按参考 (reference) 过滤：

    ```bash
    docker image ls --filter "reference=busy*"
    ```

    这会匹配仓库名以 `busy` 开头的镜像 (通配符匹配)。
* 自定义格式输出 (Go 模板)：

  ```bash
  docker image ls --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}\t{{.Size}}"
  ```

  这样可以把输出格式化成你想要的表格 (或者其他格式)。