docker image pull
| 描述 | 從登錄檔下載映象 |
|---|---|
| 用法 | docker image pull [OPTIONS] NAME[:TAG|@DIGEST] |
| 別名 | docker pull |
描述
您的大多數映象將基於 Docker Hub 登錄檔中的基礎映象建立。
Docker Hub 包含許多預構建映象，您可以 pull 並試用它們，而無需自己定義和配置。
要下載特定映象或一組映象（即倉庫），請使用 docker image 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 將終止拉取操作。