docker pull 指令：下載映像檔（--platform、-q、指定 digest）

Q: 重複執行 docker pull 會重新下載映像檔嗎？

若映像檔已是最新，輸出會顯示 Image is up to date；範例的 digest 與映像檔參照也和第一次下載相同。

Q: 如何固定下載的映像檔版本？

在映像檔名稱後使用 @sha256: 加上 digest，例如 alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0。

Q: tag 不存在時會看到什麼錯誤？

範例中的 nginx:9.99 回報 not found，指出 registry 找不到該映像檔參照。

Q: 指定 --platform 後，映像檔一定會以該平台出現在 inspect 結果嗎？

範例指定 linux/arm64 拉取後，docker image inspect 顯示 linux/amd64；可用 docker images --tree 查看該映像檔列出的多個平台變體。

docker pull 從映像檔倉庫下載映像檔；映像檔與標籤的概念見映像檔。

語法

docker pull [參數] 名稱[:標籤|@摘要]

參數

參數	說明
`-a, --all-tags`	下載該 repository 中所有有標籤的映像檔
`--platform 字串`	若伺服器支援多平台，指定要下載的平台
`-q, --quiet`	隱藏詳細輸出

範例

下載映像檔與再次拉取

$ docker pull alpine:3.23
3.23: Pulling from library/alpine
5e9b4a97f639: Pulling fs layer
5e9b4a97f639: Download complete
97ab9557f126: Download complete
79dff55e92ba: Download complete
5e9b4a97f639: Pull complete
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Downloaded newer image for alpine:3.23
docker.io/library/alpine:3.23

$ docker pull alpine:3.23
3.23: Pulling from library/alpine
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Image is up to date for alpine:3.23
docker.io/library/alpine:3.23

第一次拉取顯示圖層下載進度、digest，以及 Downloaded newer image 狀態。
再次拉取時，digest 相同且顯示 Image is up to date，沒有重複列出圖層下載進度。
未指定 registry 時，輸出的完整名稱是 docker.io/library/alpine:3.23。

安靜模式與不存在的 tag

$ docker pull -q redis:8-alpine
docker.io/library/redis:8-alpine

$ docker pull nginx:9.99
Error response from daemon: failed to resolve reference "docker.io/library/nginx:9.99": docker.io/library/nginx:9.99: not found

-q 隱藏下載進度等詳細輸出，範例只印出映像檔完整名稱。
tag 9.99 找不到時，daemon 回報 not found，並列出無法解析的完整映像檔參照。

指定平台與查看平台變體

$ docker pull --platform linux/arm64 alpine:3.23
3.23: Pulling from library/alpine
197a036d7c64: Pulling fs layer
197a036d7c64: Download complete
4f0cdf9143b4: Download complete
8b7a0920489a: Download complete
197a036d7c64: Pull complete
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Image is up to date for alpine:3.23
docker.io/library/alpine:3.23

$ docker image inspect -f '{{.Os}}/{{.Architecture}}' alpine:3.23
linux/amd64

$ docker images --tree alpine:3.23
IMAGE                   ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:3.23             ff7f0c727dd7       26.6MB         8.21MB        
├─ linux/amd64          3d67941fed5a       12.9MB         3.85MB        
├─ linux/arm/v6         806bbcf86639           0B             0B        
├─ linux/arm/v7         b43a13ac240c           0B             0B        
├─ linux/arm64/v8       8793abc47938       13.5MB         4.19MB        
├─ linux/386            7811c228ca81           0B             0B        
├─ linux/ppc64le        cc3ef1f3240a           0B             0B        
├─ linux/riscv64        1e12543f1917           0B             0B        
└─ linux/s390x          ac74ebe0c48b           0B             0B

--platform linux/arm64 下載了 arm64 版本的圖層，但狀態仍是 Image is up to date：alpine:3.23 是多平台映像檔，名稱和 digest 都沒變，只是本機多了另一個平台的內容。
因此 docker image inspect 預設顯示的仍是本機平台 linux/amd64；要看其他平台，用下面的 docker images --tree。
docker images --tree 列出 amd64、arm64/v8 等平台變體；這裡 arm64/v8 的磁碟使用量是 13.5MB。

用 digest 固定映像檔版本

$ docker pull alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker.io/library/alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0: Pulling from library/alpine
d0c1d894c237: Pulling fs layer
d0c1d894c237: Download complete
d836c7fd48f4: Download complete
047d62850641: Download complete
d0c1d894c237: Pull complete
Digest: sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
Status: Downloaded newer image for alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker.io/library/alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0

$ docker images alpine
IMAGE                                                                            ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:3.23                                                                      ff7f0c727dd7       26.6MB         8.21MB        
alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0   85fe1e81d675         13MB         3.94MB

在映像檔名稱後加上 @sha256: 與 digest，可用 digest 指定映像檔，而不是使用可變動的 tag。
輸出中的 Digest 與指定的 digest 相同，狀態為 Downloaded newer image。
docker images alpine 同時列出 alpine:3.23 與 digest 形式的參照，兩者的 ID 不同：這個 digest 是較早的 3.23 版本，而 3.23 這個 tag 之後已指向更新的建置。這正是用 digest 固定版本的原因：tag 會移動，digest 不會。

動手練習

練習：用 digest 拉取題目中的 Alpine 映像檔，並查看本機 Alpine 映像檔清單。

答案

docker pull alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker images alpine

常見問題

重複執行 docker pull 會重新下載映像檔嗎？

若映像檔已是最新，輸出會顯示 Image is up to date；範例的 digest 與映像檔參照也和第一次下載相同。

如何固定下載的映像檔版本？

在映像檔名稱後使用 @sha256: 加上 digest，例如 alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0。

tag 不存在時會看到什麼錯誤？

範例中的 nginx:9.99 回報 not found，指出 registry 找不到該映像檔參照。

指定 --platform 後，映像檔一定會以該平台出現在 inspect 結果嗎？

範例指定 linux/arm64 拉取後，docker image inspect 顯示 linux/amd64；可用 docker images --tree 查看該映像檔列出的多個平台變體。

更新於 2026年10月26日