docker image pull
| 描述 | 從登錄伺服器 (registry) 下載映像檔 |
|---|---|
| 使用方式 | docker image pull [選項] 名稱[:標籤|@摘要] |
| 別名 | docker pull |
描述
大部分的映像檔都會建立在 Docker Hub 登錄伺服器中的基礎映像檔之上。
Docker Hub 包含許多預先建置好的映像檔，您可以直接 pull 下來使用，而無需自行定義與設定。
若要下載特定的映像檔或一組映像檔（即儲存庫），請使用 docker pull。
代理設定
如果您位於 HTTP 代理伺服器後方（例如在企業環境中），在連線至登錄伺服器之前，可能需要設定 Docker 常駐程式 (daemon) 的代理設定。詳情請參閱 dockerd 命令列參考文件。
並行下載
預設情況下，Docker 常駐程式每次會拉取三個映像檔層。若您的網路頻寬較低，這可能會導致逾時問題，您可以透過 --max-concurrent-downloads 常駐程式選項來調低此數值。詳情請參閱 常駐程式文件。
選項
| 選項 | 預設值 | 描述 |
|---|---|---|
-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 使用內容定址 (content-addressable) 儲存庫，映像檔 ID 為涵蓋映像檔設定與層的 SHA256 摘要。在上述範例中，debian:bookworm 和 debian:latest 具有相同的映像檔 ID，因為它們是標記為不同名稱的同一個映像檔。由於是同一個映像檔，它們的層只會儲存一次，不會額外佔用磁碟空間。
如需更多關於映像檔、層和內容定址儲存庫的資訊，請參閱瞭解映像檔、容器與儲存驅動程式。
透過摘要（不可變識別碼）拉取映像檔
到目前為止，您都是透過名稱（和「標籤」）來拉取映像檔。使用名稱和標籤是操作映像檔的便捷方式。使用標籤時，您可以再次執行 docker pull 以確保取得該映像檔的最新版本。例如，docker pull ubuntu:24.04 會拉取 Ubuntu 24.04 映像檔的最新版本。
在某些情況下，您不希望映像檔更新至較新版本，而是偏好使用固定的映像檔版本。Docker 允許您透過摘要 (digest) 來拉取映像檔。當以摘要拉取時，您能明確指定要拉取的映像檔版本。這樣做可以將映像檔「鎖定」在特定版本，並保證您使用的映像檔始終保持一致。
若要取得映像檔的摘要，請先拉取該映像檔。讓我們從 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:// 協定與其通訊。詳細資訊請參閱不安全的登錄伺服器 (insecure registries) 章節。
拉取包含多個映像檔的儲存庫 (-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 會終止拉取操作。