docker 报 Conflict. The container name "/xxx" is already in use（容器名被占用）

你会遇到什么

同一个名字的容器第二次 docker run --name xxx ... 时报 docker: Error response from daemon: Conflict. The container name "/xxx" is already in use by container "..."。

脚本重跑、CI 重试、照着教程起服务最常见——容器名是 daemon 全局唯一资源：docker stop 之后名字还占着，而且 docker ps（不带 -a）根本看不到它，容易误判「名字空闲」。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

--name 在容器 create 时把名字登记到 daemon 的全局名字索引；docker stop 只把容器状态改为 exited，容器对象和它的名字都还在；只有 docker rm 才删除容器对象、释放名字。所以「第二次跑同一个命令」必然撞名。compose 不报这个错，是因为它重建前自己先移除旧容器。

容器生命周期是 create → start → stop → rm：名字在 create 时占用、rm 时释放，stop 不释放。报错里 by container "一串id" 就是当前占名者，docker ps -a 一定能查到它——docker ps 只显示运行中容器，退出容器必须加 -a。

确定性推论：要么 docker rm -f 删掉占名者，要么换个 --name，没有第三条路；脚本/CI 里「先删后建」是幂等标准写法。

一步步来

1. 找到占名者 — 必做

docker ps -a | grep <名字>

已退出容器 docker ps 看不到，必须 -a。

2. 确认它没用了再删 — 必做

docker rm -f <名字>    # 正在运行的容器用 -f 强删；没在跑的直接 rm

3. 旧容器还有用就换名 — 按场景

docker rename <旧名> <新名>        # 或新容器用另一个 --name

怎么确认修好了

docker ps -a | grep <名字> 无同名容器；重新 docker run --name <名字> 成功返回容器 id，且无 Conflict 报错。

其它环境的表现

症状

docker: Error response from daemon: Conflict. The container name "/repro-conflict" is already in use by container "49e3c7e4...". You have to remove (or rename) that container to be able to reuse that name.

Run 'docker run --help' for more information

特征：docker run --name 第二次用同一个名字；报错里带完整的 Conflict. The container name "..." is already in use 原文和占名容器 id。

原因

容器名是 daemon 全局唯一资源，create 时登记、rm 时才释放，stop 不释放。同名二次创建直接 Conflict；docker ps 只显示运行中容器，容易误判「名字空闲」。

解法

1. docker ps -a | grep <名字> 找占名者；
2. 没用了就 docker rm -f <名字>；还有用就 docker rename 或换新名字；
3. 脚本/CI 养成习惯：先 docker rm -f 再 docker run --name（幂等），或加 || true 容错。

相关 canonical

按「前置 → 同根 / 同域 / 相关」读：

• 相关（报错相近，根因不同）：
• Docker daemon 连不上（撞名前先确认 daemon 活着）