docker image pull
| 描述 | 從登錄檔下載映象 |
|---|---|
| 用法 | docker image pull [OPTIONS] NAME[:TAG|@DIGEST] |
| 別名 | docker pull |
描述
您的大多數映象都將基於 Docker Hub 登錄檔中的基礎映象建立。
Docker Hub 包含許多預構建的映象，您可以直接 `pull` 並嘗試，無需自行定義和配置。
要下載特定映象或一組映象（即倉庫），請使用 `docker pull`。
代理配置
如果您位於 HTTP 代理伺服器之後（例如在公司環境中），在開啟與登錄檔的連線之前，您可能需要配置 Docker 守護程序的代理設定，詳情請參閱 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 使用內容可定址的映象儲存，映象 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 會終止拉取操作。