docker pull 报 manifest for "xxx:latest" not found（镜像或标签不存在）

你会遇到什么

docker pull some/image:latest（或 run 一个不存在的镜像）报 Error response from daemon: manifest for some/image:latest not found: manifest unknown。

镜像「不存在」有四种常见真相：仓库名拼错、标签不存在、私有仓库没登录、镜像被作者删了/改了 tag。另外注意：国内镜像加速器会把这条错误改头换面成 403（见下），认不出就白折腾。

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

为什么会这样

docker pull 的链路是：CLI → registry 的 manifest API（/v2/<仓库>/manifests/<标签>）→ 拿到清单后再按层下载。manifest 查询返回 404 = daemon 转成 manifest for xxx not found。

latest 不是特殊魔法值，只是一个默认标签：作者不推 latest 就只有具体版本标签；镜像被删/私有化同样 404。

镜像 = manifest（清单，描述层与配置）+ 若干层 blob。pull 第一步只查 manifest，这一步的 404 直接对应「这个仓库+标签组合在 registry 上不存在」。daemon 的报错文案固定为 manifest for <image>:<tag> not found: manifest unknown（Docker Hub 官方形态）。

国内加速器（daemon.json 的 registry-mirrors）是「代理 registry」：本机实测（daocloud 镜像源）对不存在的标签返回 403 Forbidden 而不是 404/manifest unknown——它把上游 404 伪装成自己的状态码，是镜像站自身行为，不是你的配置问题。

确定性推论：报 manifest unknown/not found = registry 上确实没这组合，先查仓库名拼写、tag 是否真实存在（docker manifest inspect 或 registry 网页），私有仓库再考虑 docker login；

报 403 Forbidden from https://<镜像站>/v2/... 且直连 Docker Hub 正常 = 镜像站行为，换镜像源或直接去上游仓库页面核对。

一步步来

1. 确认拼写与标签 — 必做

docker manifest inspect <仓库>:<标签>   # 报 not found = 远端真没有
docker search <仓库>                    # 确认仓库名拼写

2. 按场景分流 — 按场景

• 仓库名拼错 → 去 Docker Hub / 源仓库页面复制准确名称；
• 只有版本标签没有 latest → 明确写版本号：docker pull redis:7-alpine；
• 私有仓库 → docker login <registry> 后再拉；
• 镜像被删/迁移（如从 Docker Hub 迁到 ghcr.io）→ 用新地址。

3. 国内加速器 403 变体 — 按诊断结果

报 unexpected status from HEAD request to https://<镜像站>/v2/... 403 Forbidden 时：先 docker info 看当前 Registry Mirrors，直接访问上游仓库页面确认 tag 是否存在；

镜像站把上游 404 改写成 403，换一个镜像源（改 /etc/docker/daemon.json 的 registry-mirrors）通常就能看到真实状态。

怎么确认修好了

docker manifest inspect <仓库>:<tag> 返回 JSON 清单；docker pull <仓库>:<tag> 正常下载层。

其它环境的表现

症状

# 标准形态（Docker Hub 直连）
Error response from daemon: manifest for some/image:latest not found: manifest unknown

# 本机实测形态（daocloud 镜像源，2026-08-31）
Error response from daemon: unknown: failed to resolve reference "docker.io/library/alpine:definitely-no-tag-xyz":
unexpected status from HEAD request to https://docker.m.daocloud.io/v2/library/alpine/manifests/definitely-no-tag-xyz?ns=docker.io: 403 Forbidden

特征：报错里带「仓库:标签」完整引用；manifest ... not found = registry 上没这组合；镜像站域名 + 403 = 加速器把上游 404 改写了。

原因

pull 第一步查 manifest API，404 → daemon 报 manifest not found。latest 只是默认标签不是保证；镜像被删/改名/私有化/拼错都表现为 not found。镜像加速器是代理层，会把上游 404 改写成自己的状态码（实测 403），识别特征 = 报错 URL 是镜像站域名。

解法

1. docker manifest inspect 确认远端存在性；
2. 拼错改拼写、无 latest 写版本号、私有仓库先 docker login、被删/迁移换地址；
3. 镜像站 403 变体 = 换镜像源或直连上游验证。

相关 canonical

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

• 同根（同一根因）：
• Docker Hub 拉取失败（网络层失败：connection reset / no such host——与「镜像不存在」同症状族、不同根因）