# docker image rm

从本地主机节点删除一个或多个镜像。

## 用法

```bash
docker image rm [OPTIONS] IMAGE [IMAGE...]
```

### 别名

* `docker image remove`
* `docker rmi`

该命令用于从本地系统中**删除（并取消标签）一个或多个镜像**。

* 如果某个镜像有多个标签（tag），当你使用某个标签作为参数执行此命令时，**仅会移除该标签**。
* 如果该标签是该镜像**唯一的引用**，那么镜像本身和该标签都会被删除。
* 此命令**不会从远程镜像仓库（registry）中删除镜像**。
* 如果镜像正被某个**正在运行的容器使用**，则无法删除，除非使用 `-f`（强制）选项。
* 要查看主机上所有镜像，请使用 `docker image ls` 命令。

你可以通过以下任一方式指定要删除的镜像：

* 镜像的短 ID 或完整 ID
* 镜像的标签（如 `nginx:latest`）
* 镜像的摘要（digest，如 `@sha256:...`）

> ⚠️ 注意：如果一个镜像有多个标签指向它，你必须先删除所有这些标签，才能彻底删除该镜像。否则会报冲突错误。

## 选项

\| 短选项 | 长选项 | 默认值 | 描述 | | | | | -- | | `-f` | `--force` | 无 | 强制删除镜像（即使有容器在使用） | | 无 | `--no-prune` | 无 | 不删除未打标签的父镜像层 |

## 示例

### 示例 1：尝试直接通过镜像 ID 删除多标签镜像（失败）

```bash
$ docker images
REPOSITORY   TAG      IMAGE ID       CREATED        SIZE
test1        latest   fd484f19954f   23 seconds ago 7 B (virtual 4.964 MB)
test         latest   fd484f19954f   23 seconds ago 7 B (virtual 4.964 MB)
test2        latest   fd484f19954f   23 seconds ago 7 B (virtual 4.964 MB)

$ docker rmi fd484f19954f
Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force
```

### 示例 2：逐个删除标签

```bash
$ docker rmi test1:latest
Untagged: test1:latest

$ docker rmi test2:latest
Untagged: test2:latest

$ docker images
REPOSITORY   TAG      IMAGE ID       CREATED        SIZE
test         latest   fd484f19954f   23 seconds ago 7 B (virtual 4.964 MB)

$ docker rmi test:latest
Untagged: test:latest
Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
```

此时镜像及其所有层都被成功删除。

### 示例 3：使用 `-f` 强制删除所有引用

```bash
$ docker images
REPOSITORY   TAG      IMAGE ID       CREATED        SIZE
test1        latest   fd484f19954f   23 seconds ago 7 B (virtual 4.964 MB)
test         latest   fd484f19954f   23 seconds ago 7 B (virtual 4.964 MB)
test2        latest   fd484f19954f   23 seconds ago 7 B (virtual 4.964 MB)

$ docker rmi -f fd484f19954f
Untagged: test1:latest
Untagged: test:latest
Untagged: test2:latest
Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
```

### 示例 4：删除通过摘要（digest）拉取的镜像

某些镜像通过摘要拉取，没有标签：

```bash
$ docker images --digests
REPOSITORY                 TAG    DIGEST                                                                    IMAGE ID       CREATED      SIZE
localhost:5000/test/busybox <none> sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf   4986bf8c1536   9 weeks ago  2.43 MB
```

通过完整引用删除：

```bash
$ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125
Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2
Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b
```

> 💡 提示：当通过标签删除镜像时，其对应的摘要引用会自动被移除。