docker push 命令教程：将镜像推送到 Registry（--all-tags、docker login）

Q: 推送镜像前为什么要添加 Registry 标签？

docker tag 会创建一个指向源镜像的目标名称；示例将 alpine:3.23 标记为 localhost:5000/tools/alpine:3.23，然后推送该名称。

Q: docker push --all-tags 会推送哪些标签？

它会推送指定 Repository 的所有标签。示例中，tools/alpine 的 3.23 和 latest 都会被推送。

Q: 推送到 Docker Hub 时出现 insufficient_scope 怎么办？

这表示你没有权限推送到这个 Repository。示例中的 docker.io/library/alpine 是 Docker 官方镜像的命名空间，任何个人账号都不能向其中推送。要推送到 Docker Hub，请先运行 docker login，再将镜像标记为 你的账号/名称:标签 后推送，参见 [推送到 Docker Hub](/zh/docker/docker-hub/)。

docker push 会将镜像上传到 Registry，通常要先使用 docker tag 设置目标名称；Docker Hub 的用法请参见 Docker Hub。

语法

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
docker push [OPTIONS] NAME[:TAG]
docker login [OPTIONS] [SERVER]

参数

参数	说明
`-a, --all-tags`	推送镜像的所有标签
`--platform 字符串`	将指定平台的 manifest 作为单平台镜像推送；不会推送 image index，因此不会保留其他 manifest（包括 attestations）。格式为 `os[/arch[/variant]]`，例如 `linux/amd64`
`-q, --quiet`	隐藏详细输出
`-p, --password 字符串`	密码或 Personal Access Token（PAT）；使用 `-` 从 stdin 读取
`--password-stdin`	从 stdin 读取密码或 Personal Access Token（PAT）
`-u, --username 字符串`	用户名

如果运行 docker login 时未指定服务器，则默认使用 Docker Hub。docker tag 的目标名称格式为 TARGET_IMAGE[:TAG]。

示例

以下示例使用本地 Registry localhost:5000，将 alpine:3.23 标记到 tools/alpine Repository。

创建目标标签

$ docker tag alpine:3.23 localhost:5000/tools/alpine:3.23

$ docker tag alpine:3.23 localhost:5000/tools/alpine:latest

$ docker images localhost:5000/tools/alpine
IMAGE                                ID             DISK USAGE   CONTENT SIZE   EXTRA
localhost:5000/tools/alpine:3.23     ff7f0c727dd7       26.6MB         8.21MB        
localhost:5000/tools/alpine:latest   ff7f0c727dd7       26.6MB         8.21MB

两个标签都指向同一个镜像 ID。
目标名称包含 Registry 主机和端口、Repository，以及各自的标签。

推送单个标签和所有标签

$ docker push localhost:5000/tools/alpine:3.23
The push refers to repository [localhost:5000/tools/alpine]
5e9b4a97f639: Unavailable
5e9b4a97f639: Pushed
3.23: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

$ docker push localhost:5000/tools/alpine:latest
The push refers to repository [localhost:5000/tools/alpine]
5e9b4a97f639: Layer already exists
latest: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

$ docker push --all-tags localhost:5000/tools/alpine
The push refers to repository [localhost:5000/tools/alpine]
5e9b4a97f639: Layer already exists
3.23: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022
5e9b4a97f639: Layer already exists
latest: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

推送单个标签时会报告 digest；再次推送相同 Layer 时会显示 Layer already exists。
--all-tags 会一次性推送 tools/alpine 的 3.23 和 latest。
Info 提示：alpine:3.23 是多平台镜像，但本地只有部分平台的内容，因此只推送了当前可用的单平台镜像（digest 从 ff7f0c… 变为单平台的 3d6794…）。推送成功，只是 Registry 中的这个标签只有一个平台。要推送多平台镜像，请参见多平台镜像。

查看 Registry 标签并识别错误

$ wget -qO- http://localhost:5000/v2/tools/alpine/tags/list
{"name":"tools/alpine","tags":["3.23","latest"]}

$ docker push localhost:5000/tools/missing:1.0
The push refers to repository [localhost:5000/tools/missing]
tag does not exist: localhost:5000/tools/missing:1.0

$ docker push docker.io/library/alpine:3.23
The push refers to repository [docker.io/library/alpine]
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Layer already exists
failed commit on ref "manifest-sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306": server message: insufficient_scope: authorization failed

Registry 的标签列表确认 3.23 和 latest 都存在；推送本地不存在的标签时会报告 tag does not exist。
推送到 Docker Hub 的 docker.io/library/alpine 时，最后出现 insufficient_scope: authorization failed：library/ 是官方镜像的命名空间，没有人能向其中推送。
要推送到 Docker Hub，必须先运行 docker login（参数见上表），并将镜像标记为自己账号下的名称，例如 你的账号/alpine:3.23。

动手练习

练习：将本地 alpine:3.23 标记为 localhost:5000/tools/alpine:latest，然后推送 tools/alpine 的所有标签。

答案

docker tag alpine:3.23 localhost:5000/tools/alpine:latest
docker push --all-tags localhost:5000/tools/alpine

常见问题

推送镜像前为什么要添加 Registry 标签？

docker tag 会创建一个指向源镜像的目标名称；示例将 alpine:3.23 标记为 localhost:5000/tools/alpine:3.23，然后推送该名称。

`docker push --all-tags` 会推送哪些标签？

它会推送指定 Repository 的所有标签。示例中，tools/alpine 的 3.23 和 latest 都会被推送。

推送到 Docker Hub 时出现 insufficient_scope 怎么办？

这表示你没有权限推送到这个 Repository。示例中的 docker.io/library/alpine 是 Docker 官方镜像的命名空间，任何个人账号都不能向其中推送。要推送到 Docker Hub，请先运行 docker login，再将镜像标记为 你的账号/名称:标签 后推送，参见 [推送到 Docker Hub](/zh/docker/docker-hub/)。

推送成功后出现单平台 Info 是失败了吗？

示例已报告标签的 digest，随后显示只推送了当前可用的单平台镜像。这是 Info 提示，并不表示本次推送失败。

更新于 2026年10月26日