docker image pull

說明	從 Registry 下載映像檔
用法	`docker image pull [選項] 名稱[:標籤\|@摘要]`
別名	`docker pull`

預設情況下，Docker Daemon 一次會提取映像檔的三個層級。如果您使用的是低頻寬連線，這可能會導致逾時問題，您可能需要透過 Daemon 選項 `--max-concurrent-downloads` 來降低此設定。詳細資訊請參閱 Daemon 文件。

選項

選項	預設值	說明
`-a, --all-tags`		下載儲存庫中所有已標記的映像檔
`--disable-content-trust`	`true`	略過映像檔驗證
`--platform`		API 1.32+ 如果伺服器支援多平台，則設定平台
`-q, --quiet`		隱藏詳細輸出

範例

從 Docker Hub 下載映像檔

要下載特定映像檔或一組映像檔（即儲存庫），請使用 docker image pull（或簡寫 docker pull）。如果未提供標籤，Docker Engine 會使用 :latest 標籤作為預設值。此範例提取 debian:latest 映像檔。

$ docker image pull debian

Using default tag: latest
latest: Pulling from library/debian
e756f3fdd6a3: Pull complete
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:latest
docker.io/library/debian:latest

Docker 映像檔可以由多個層組成。在上面的範例中，映像檔由單個層組成：e756f3fdd6a3。

映像檔可以重複使用層。例如，debian:bookworm 映像檔與 debian:latest 共用其層。因此，提取 debian:bookworm 映像檔只會提取其詮釋資料，而不會提取其層，因為該層已在本機存在。

$ docker image pull debian:bookworm

bookworm: Pulling from library/debian
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:bookworm
docker.io/library/debian:bookworm

要查看本機存在哪些映像檔，請使用 docker images 命令。

$ docker images

REPOSITORY   TAG        IMAGE ID       CREATED        SIZE
debian       bookworm   4eacea30377a   8 days ago     124MB
debian       latest     4eacea30377a   8 days ago     124MB

Docker 使用內容可定址的映像檔儲存區，映像檔 ID 是一個涵蓋映像檔配置和層的 SHA256 雜湊值。在上面的範例中，debian:bookworm 和 debian:latest 具有相同的映像檔 ID，因為它們是使用不同名稱標記的相同映像檔。由於它們是相同的映像檔，因此它們的層只儲存一次，不會消耗額外的磁碟空間。

有關映像檔、層和內容可定址儲存區的更多資訊，請參閱了解映像檔、容器和儲存驅動程式。

透過摘要（不可變識別碼）提取映像檔

到目前為止，您已經透過名稱（和「標籤」）提取了映像檔。使用名稱和標籤是使用映像檔的便捷方式。使用標籤時，您可以再次執行 docker pull 一個映像檔，以確保您擁有該映像檔的最新版本。例如，docker pull ubuntu:24.04 會提取 Ubuntu 24.04 映像檔的最新版本。

在某些情況下，您不希望映像檔更新到較新版本，而是希望使用固定版本的映像檔。Docker 允許您透過其摘要提取映像檔。透過摘要提取映像檔時，您可以精確指定要提取的映像檔版本。這樣做可以將映像檔「固定」到該版本，並確保您使用的映像檔始終相同。

要了解映像檔的摘要，請先提取映像檔。讓我們從 Docker Hub 提取最新的 ubuntu:24.04 映像檔。

$ docker pull ubuntu:24.04

24.04: Pulling from library/ubuntu
125a6e411906: Pull complete
Digest: sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
Status: Downloaded newer image for ubuntu:24.04
docker.io/library/ubuntu:24.04

Docker 在提取完成後會印出映像檔的摘要。在上面的範例中，映像檔的摘要是

sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

Docker 在推送至登錄檔時也會印出映像檔的摘要。如果您想要固定到剛推送的映像檔版本，這可能會很有用。

摘要在提取映像檔時會取代標籤，例如，要透過摘要提取上述映像檔，請執行以下命令：

$ docker pull ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

docker.io/library/ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30: Pulling from library/ubuntu
Digest: sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
Status: Image is up to date for ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
docker.io/library/ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

摘要也可以用於 Dockerfile 的 FROM 中，例如：

FROM ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
LABEL org.opencontainers.image.authors="some maintainer <maintainer@example.com>"

注意事項
使用此功能會將映像檔「固定」到特定時間點的版本。因此，Docker 不會提取映像檔的更新版本，其中可能包含安全性更新。如果要提取更新的映像檔，則需要相應地更改摘要。

從不同的登錄檔提取

預設情況下，docker pull 會從 Docker Hub 提取映像檔。也可以手動指定要提取的登錄檔路徑。登錄檔路徑類似於 URL，但不包含通訊協定說明符（https://）。

以下命令從監聽埠 5000（myregistry.local:5000）的本機登錄檔提取 testing/test-image 映像檔。

$ docker image pull myregistry.local:5000/testing/test-image

登錄檔憑證由 docker login 管理。

Docker 使用 https:// 通訊協定與登錄檔通訊，除非允許透過不安全的連線存取登錄檔。請參閱不安全登錄檔章節以了解更多資訊。

提取具有多個映像檔的儲存庫（-a，--all-tags）

預設情況下，docker pull 會從登錄檔提取單個映像檔。儲存庫可以包含多個映像檔。要從儲存庫提取所有映像檔，請在使用 docker pull 時提供 -a（或 --all-tags）選項。

此命令會從 ubuntu 儲存庫提取所有映像檔。

$ docker image pull --all-tags ubuntu

Pulling repository ubuntu
ad57ef8d78d7: Download complete
105182bb5e8b: Download complete
511136ea3c5a: Download complete
73bd853d2ea5: Download complete
....

Status: Downloaded newer image for ubuntu

提取完成後，使用 docker image ls 命令（或簡寫 docker images）查看已提取的映像檔。以下範例顯示本機存在的所有 ubuntu 映像檔。

$ docker image ls --filter reference=ubuntu
REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
ubuntu       22.04     8a3cdc4d1ad3   3 weeks ago    77.9MB
ubuntu       jammy     8a3cdc4d1ad3   3 weeks ago    77.9MB
ubuntu       24.04     35a88802559d   6 weeks ago    78.1MB
ubuntu       latest    35a88802559d   6 weeks ago    78.1MB
ubuntu       noble     35a88802559d   6 weeks ago    78.1MB

取消提取

終止 docker pull 程序，例如在終端機中執行時按下 CTRL-c，將會終止提取操作。

$ docker pull ubuntu

Using default tag: latest
latest: Pulling from library/ubuntu
a3ed95caeb02: Pulling fs layer
236608c7b546: Pulling fs layer
^C

當守護行程與用戶端（啟動提取）之間的連線因任何原因斷開或遺失，或者命令被手動終止時，Engine 會終止提取操作。